How to install uv on macOS

uv is a fast Python package and project manager. This guide covers how to install it on macOS.

Standalone installer (recommended)

The standalone installer is the recommended method because it requires no prerequisites: no Python, no package manager, nothing. It downloads a prebuilt binary and adds it to your PATH.

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

After running the installer, open a new terminal window so the updated PATH takes effect.

Alternative installation methods

The standalone installer works for most people, but you may prefer a different method depending on your setup.

Homebrew

If you already use Homebrew to manage system tools, installing uv through it keeps everything in one place:

brew install uv

Homebrew handles PATH configuration automatically. The tradeoff: Homebrew updates uv on its own schedule, so you may lag behind the latest release by a few days.

pip or pipx

If you have Python installed and prefer to manage tools through pip:

pip install uv

Or, to install it in an isolated environment with pipx:

pipx install uv

This approach creates a circular dependency (you need Python to install the tool that manages Python), so the standalone installer is usually a better choice.

Shell completions

uv can generate tab-completion scripts for your shell. This gives you autocomplete for commands, options, and arguments.

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
source ~/.bashrc

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

uv generate-shell-completion fish | source
uv generate-shell-completion fish > ~/.config/fish/completions/uv.fish

Verifying installation

After installation, open a new terminal and verify uv is working:

uv --version

You should see output like:

uv 0.x.y

If you get command not found, see the troubleshooting section below.

Troubleshooting

uv: command not found after installing

The standalone installer adds uv to ~/.local/bin by default (or $XDG_BIN_HOME if set). If your shell doesn’t include that directory in PATH, the command won’t be found.

Fix: Open a new terminal window. The installer modifies your shell profile (.bashrc, .zshrc, .config/fish/config.fish), but those changes only apply to new shell sessions. If that doesn’t work, check that the directory is on your PATH:

echo $PATH | tr ':' '\n' | grep .local/bin

If nothing prints, add it manually. For Zsh (the default shell on macOS):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission errors

If the installer fails with a permission error, the target directory may be owned by root. Avoid using sudo with the installer. Instead, ensure ~/.local/bin exists and is owned by your user:

mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local/bin

Then re-run the install script.

Learn More

• uv reference page
• uv official installation guide
• Create your first Python project
• How to upgrade uv