Python

Written & tested for accuracy by a developer (not AI)

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 installing 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
  • Creates an env script at $HOME/.local/bin/env that adds ~/.local/bin to your PATH
  • Adds a line to a shell startup file that sources that env script (on most Macs, ~/.zshrc)

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 edits a shell startup 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, it added this line to a shell startup file:

. "$HOME/.local/bin/env"

Note that the installer does not write an export PATH line directly. It writes the line above, which runs the small env script the installer created at ~/.local/bin/env. That script adds ~/.local/bin to your PATH only if it is not already there, so sourcing it more than once is harmless.

Which file gets the line? The installer uses the first of ~/.zshrc or ~/.zshenv that already exists, and creates ~/.zshrc if neither does. On most Macs the answer is ~/.zshrc. If you cannot find the line, search both files. (The separate uv tool update-shell command, described below, uses ~/.zshenv instead.)

Choose a shell configuration file

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

  • ~/.zshenv runs for every shell session, including non-interactive scripts
  • ~/.zprofile runs for login shells (what a terminal application opens by default)
  • ~/.zshrc runs for interactive shells

If you are setting the PATH yourself, use ~/.zprofile. There is a macOS-specific reason. A utility called path_helper runs from /etc/zprofile, after ~/.zshenv but before ~/.zprofile, and it rebuilds the PATH order. A directory you prepend in ~/.zshenv is still on the PATH afterward, but it gets pushed behind the system directories, so a different python3 may win. Setting the PATH in ~/.zprofile avoids that. See .zshrc or .zprofile for the full explanation.

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 command writes to ~/.zshenv, which is not the same file the curl installer usually edits. Astral chose ~/.zshenv here because it is the one Zsh file sourced for every kind of shell session, following the same approach rustup uses. Use this command if you need to repair a missing PATH entry, but check ~/.zshrc first so you do not end up with the entry in two files.

Apple Silicon vs Intel PATH note

This note is about where the uv binary lives so you can run uv commands. It is separate from ~/.local/bin, where uv places the Python executables (uv python install --default) and command-line tools (uv tool install / uvx) that it manages.

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 for the uv binary is already set. That covers the uv command only: Homebrew users still need ~/.local/bin on the PATH (the export PATH="$HOME/.local/bin:$PATH" line shown above) to run uv-managed Python and tools directly.

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.12.0

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. Because uv fetches Python for you, you never need to download Python from python.org.

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.

If you've hit error: externally-managed-environment on pip install, uv will help you avoid the error. See Fix: error: externally-managed-environment.

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

Running the wrong command is harmless. A Homebrew-installed uv refuses to update itself and points you to brew update && brew upgrade uv instead. See Brew Install uv for details on updating and managing the Homebrew installation.

Important: keep uv current whichever method you used. The list of Python versions uv can install is frozen at each uv release, so an out-of-date uv installs an out-of-date Python.

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, remove any uv-related PATH entries. Check ~/.zshrc first (the usual target of the curl installer), then ~/.zshenv (used by uv tool update-shell) and ~/.zprofile if you set the PATH yourself. You are looking for the line . "$HOME/.local/bin/env".

Migrate from Rye to uv

If you have been using Rye for Python project management, you should migrate to uv. Rye is no longer developed: Astral stopped work on it in February 2025, the repository is archived, and no further updates are planned, including security updates. Astral describe uv as the successor project from the same maintainers, and it 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.
  • Two copies of uv: running both the Homebrew installer and the curl installer leaves two uv binaries, and PATH order decides which one runs. Use which -a uv to list them, then uninstall the one you do not want. Update commands cannot cause this, because a Homebrew-installed uv refuses to update itself.
  • 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.