Python

There is no AI here. All content is human-authored and tested for accuracy.

Install uv on Mac

How to install uv on Mac. Use the official installer or Homebrew to set up uv, the fast Python package and project manager. Covers PATH setup for Zsh, installing Python, creating your first project, and managing packages with uv on macOS.

The tool uv is an extremely fast Python package and project manager from Astral, written in Rust. It replaces separate tools such as pip, pyenv, virtualenv, and pipx with a single program that is 10-100x faster. See uv for Python on Mac for a detailed comparison of uv with other Python tools.

Installing Python is one step in setting up your Mac for development. See the Mac development setup guide.

Before you get started

You will need a terminal application to install uv and run Python commands. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

First steps to install uv on Mac

First, check the macOS version. If you're running an older version, update macOS to the latest macOS version.

You will also need Xcode Command Line Tools before installing uv, unless you've already installed HomeBrew, which installs Xcode Command Line Tools for you. The Command Line Tools provide basic Unix utilities that uv requires. Check if they are installed:

$ xcode-select -p

If you see a path such as /Library/Developer/CommandLineTools, you are ready to proceed. If not, install them:

$ xcode-select --install

Follow the prompts to complete the installation. See Xcode Command Line Tools if you need more detail.

Choose an installation method

You can install uv in two ways on Mac: HomeBrew or the official curl installer. Use Homebrew if you already manage most developer tools with brew and prefer one package manager for everything. See Brew Install uv for the full Homebrew guide. Use the official installer if you want the latest version and built-in self-update capability. Astral, the developer, recommends installng uv on Mac with the official installer script.

Install uv with the official installer

There is no need to install Homebrew or Python before installing uv with the official installer. It handles everything.

Run this command in your terminal:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

The curl command downloads the install script from Astral and pipes it to sh for execution. The installer performs three actions:

  • Installs the uv and uvx binaries to ~/.local/bin
  • Modifies your shell configuration file (~/.zshenv by default) to add ~/.local/bin to your PATH
  • Creates an env file at $HOME/.local/bin/env for activating uv in the current session

The installer does not require admin privileges or sudo.

After the installer finishes, you can activate uv in your current terminal session without opening a new window:

$ source $HOME/.local/bin/env

The installer creates this env file as a shortcut for loading uv into your PATH. Alternatively, open a new terminal window, which reads the updated shell configuration automatically.

View installer options

If you want to see what options are available before running the installer, use the help flag:

$ curl -LsSf https://astral.sh/uv/install.sh | sh -s -- --help

Change the install directory

By default, uv installs to ~/.local/bin. To change the install location, set the UV_INSTALL_DIR environment variable:

$ curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/custom/path" sh

I don't recommend changing the install location because it makes maintenance more difficult.

Disable automatic PATH modification

The installer modifies your ~/.zshenv file automatically. If you prefer to set up the PATH yourself, disable the automatic behavior:

$ curl -LsSf https://astral.sh/uv/install.sh | env INSTALLER_NO_MODIFY_PATH=1 sh

Then set the PATH manually as described below.

Install uv with Homebrew

If you already use Homebrew, you can install uv with one command:

$ brew install uv

See Brew Install uv for the full Homebrew installation guide, including how Homebrew uv differs from the official installer and how to update safely.

Choose Homebrew if you want uv managed alongside your other Homebrew packages. Choose the official installer if you want the latest version immediately and a self-update capability.

Set the PATH for uv on Mac

The PATH is an environment variable that tells the shell where to find programs. After installing uv, your PATH must include the directory containing the uv binary so you can run uv from any location.

Automatic PATH setup

If you used the official installer without disabling PATH modification, the installer added this line to your ~/.zshenv file:

export PATH="$HOME/.local/bin:$PATH"

The file ~/.zshenv runs for all Zsh sessions (both login and interactive shells), so uv will be available everywhere. This works automatically for new terminal windows.

Choose a shell configuration file

On macOS, Zsh reads several configuration files in a specific order:

  • ~/.zshenv runs for every shell session (the installer's default target)
  • ~/.zprofile runs for login shells (what a terminal application opens by default)
  • ~/.zshrc runs for interactive shells

Many developers prefer to set the PATH in ~/.zprofile rather than ~/.zshenv. Either approach works. See .zshrc or .zprofile for a full explanation of the difference. The important thing is that ~/.local/bin appears in your PATH.

Set the PATH manually

If you disabled automatic PATH modification or installed uv with Homebrew, add the PATH entry yourself. See Shell Configuration for more about editing shell configuration files.

Add this line at the end of the file:

export PATH="$HOME/.local/bin:$PATH"

Save the file and apply the changes:

$ source ~/.zprofile

The source command re-reads the configuration file in your current session. Alternatively, open a new terminal window.

Use uv tool update-shell

The tool uv provides a built-in command to set up your PATH, as an alternative to manually editing the configuration file.

$ uv tool update-shell

This adds ~/.local/bin to your ~/.zshenv file. It is the same PATH entry that the official installer creates automatically. Use this command if you need to repair a missing PATH entry.

Apple Silicon vs Intel PATH note

If you installed uv with Homebrew, the binary location depends on your Mac's processor. For the official curl installer, the path is always ~/.local/bin regardless of processor.

On Apple Silicon (M-series), Homebrew installs to /opt/homebrew/bin:

export PATH="/opt/homebrew/bin:$PATH"

On Intel Macs, Homebrew uses /usr/local/bin:

export PATH="/usr/local/bin:$PATH"

Most Macs sold since late 2020 use Apple Silicon. If Homebrew commands already work in your terminal, the correct path is already set.

Check the PATH

After setting up your PATH, verify it contains the uv binary directory:

$ echo $PATH

You should see ~/.local/bin (or the Homebrew bin directory) in the output. The leftmost directory in the PATH takes precedence over directories to its right.

Verify uv installation

Confirm that uv is installed and accessible:

$ uv --version
uv 0.7.2

You should see a version number (yours may be newer). If you see zsh: command not found: uv instead, see Command not found: uv for troubleshooting steps.

Install Python with uv

One of the main features of uv is its ability to install and manage Python versions. These Python installations are separate from the system Python (installed with Xcode Command Line Tools) and any Homebrew Python.

Install the latest stable Python version:

$ uv python install

To install a specific version:

$ uv python install 3.12

You should not attempt to update or remove the system Python installed with Xcode Command Line Tools. Just install newer versions alongside it with uv.

Verify Python installation

Check which Python versions uv has installed:

$ uv python list --only-installed

Find which Python version uv will use by default:

$ uv python find

Check where uv stores Python installations:

$ uv python dir

The tool uv keeps Python versions in ~/.local/share/uv/python/. Each version is self-contained and does not interfere with other installations.

Start a Python project with uv

Create a new project with uv init, which generates a pyproject.toml file and sets up the project structure:

$ uv init myproject
$ cd myproject

Add a dependency to your project:

$ uv add <package>

The command uv add updates the pyproject.toml file, resolves dependencies, and installs packages into an automatically created virtual environment (.venv/ in the project directory). There is no need to run python -m venv or install virtualenv separately.

Run a script within the project environment:

$ uv run python script.py

The command uv run ensures the correct Python version and all project dependencies are available.

Pin a Python version for a project

Set a specific Python version for a project:

$ uv python pin 3.12

This creates a .python-version file in the project directory. The tool uv will use this version for all commands in the project.

Use uv as a pip replacement

If you are following a tutorial that uses pip commands, uv provides a compatible interface:

$ uv pip install requests
$ uv pip compile requirements.in -o requirements.txt

These commands work like pip but are significantly faster.

Run tools with uvx

Run Python command-line tools (for example, ruff) in ephemeral environments without installing them permanently:

$ uvx ruff check .

To install a tool permanently:

$ uv tool install ruff

The uvx command is a shortcut for uv tool run. It downloads and runs the tool in an isolated environment that is cleaned up automatically. Installed tools are placed in ~/.local/bin so they are available from the command line.

Enable shell autocompletion for uv

Set up tab completion for uv commands in Zsh (the default macOS shell):

$ echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

Restart your terminal or run source ~/.zshrc to activate autocompletion. Tab completion makes it easier to discover uv subcommands and options.

Update uv

How you update uv depends on how you installed it.

If you installed uv with the official installer, use the self-update command:

$ uv self update

If you installed uv with Homebrew, use the Homebrew upgrade command:

$ brew upgrade uv

Important: do not run uv self update if you installed uv with Homebrew. See Brew Install uv for details on updating and managing the Homebrew installation.

Uninstall uv

If you decide to remove uv, first clean up stored data (optional):

$ uv cache clean
$ rm -r "$(uv python dir)"
$ rm -r "$(uv tool dir)"

Remove the uv binaries. For the official installer:

$ rm ~/.local/bin/uv ~/.local/bin/uvx

For Homebrew installations:

$ brew uninstall uv

If the installer modified your shell configuration files, edit ~/.zshenv or ~/.zprofile to remove any uv-related PATH entries.

Migrate from Rye to uv

If you have been using Rye for Python project management, you should migrate to uv. Both tools were created by Charlie Marsh at Astral. Rye is now in maintenance mode, and uv is the recommended replacement. Rye projects use pyproject.toml, which uv also supports.

To migrate an existing Rye project, navigate to the project directory and run:

$ uv sync

This reads the existing pyproject.toml and installs all dependencies. Use uv run in place of rye run to execute project commands. Use uv add in place of rye add to add new dependencies.

Troubleshooting uv on Mac

If you run into problems installing or running uv, check these common issues:

  • zsh: command not found: uv after installing: your PATH does not include ~/.local/bin or the Homebrew bin directory. See Command not found: uv for step-by-step fixes.
  • Mixing update methods: if you installed uv with Homebrew but ran uv self update (or vice versa), you may have conflicting installations. Uninstall one method and reinstall with the other.
  • Shell configuration not loading: macOS reads .zprofile for login shells and .zshrc for interactive shells. If PATH changes are not taking effect, you may have edited the wrong file. See .zshrc or .zprofile for an explanation.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.