# How to install uv on macOS


[uv](https://pydevtools.com/handbook/reference/uv.md) 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`.

```bash
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](https://pydevtools.com/handbook/reference/homebrew.md) to manage system tools, installing uv through it keeps everything in one place:

```bash
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:

```bash
pip install uv
```

Or, to install it in an isolated environment with [pipx](https://pydevtools.com/handbook/reference/pipx.md):

```bash
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.

```bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
source ~/.bashrc
```
```bash
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc
source ~/.zshrc
```
```bash
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:

```bash
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`:

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

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

```bash
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:

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

Then re-run the install script.

## Learn More

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.
- [uv reference page](https://pydevtools.com/handbook/reference/uv.md)
- [uv official installation guide](https://docs.astral.sh/uv/getting-started/installation/)
- [Create your first Python project](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md)
- [How to upgrade uv](https://pydevtools.com/handbook/how-to/how-to-upgrade-uv.md)