Python

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

Brew Install uv

Brew install uv on Mac. How to install the uv Python package manager with Homebrew. Covers brew install uv, verification, updates with brew upgrade uv, and how Homebrew uv compares to the official curl installer.

Here is how to install uv, the fast Python package and project manager, with Homebrew on Mac. If you already use Homebrew for managing development tools, installing uv with brew install uv keeps everything in one place. See uv for Python on Mac for an overview of what uv does and how it compares with other Python tools. If you do not use Homebrew, see Install uv on Mac for the official installer method.

Installing uv is one step in setting up your Mac for development. See the complete Mac setup checklist.

Before you get started

You will need a terminal application to install uv with Homebrew. 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 is FREE and worth a try.

First steps to brew install uv

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

You will need Homebrew installed before you can use brew install. If you do not have Homebrew, see Install Homebrew.

Check that Homebrew is ready

Verify Homebrew is installed:

$ brew --version

You should see output such as Homebrew 5.1.0. If you see zsh: command not found: brew, Homebrew is not installed or not in your PATH. See Zsh: command not found: brew for troubleshooting.

Update Homebrew before installing any new package:

$ brew update

This updates Homebrew's package index so you get the latest version of uv. The update can take a moment if you have not run it recently.

Optionally, run brew doctor to check that Homebrew is configured correctly:

$ brew doctor
Your system is ready to brew.

If brew doctor reports warnings, resolve them before installing new packages.

Install uv with Homebrew

Install uv with a single command:

$ brew install uv

Homebrew downloads the uv binary, places the files in its Cellar directory, and creates a symlink in the Homebrew bin directory. On Apple Silicon (M-series) Macs, the symlink is at /opt/homebrew/bin/uv. On Intel Macs, it is at /usr/local/bin/uv.

No additional PATH setup is needed to run uv itself if Homebrew is configured correctly. Homebrew adds its bin directory to your PATH during its own installation, so if Homebrew commands already work, the uv command will too.

That covers the uv command, but not everything uv installs. The Python executables and command-line tools that uv manages are placed in ~/.local/bin, which is not the Homebrew bin directory and is not on your PATH by default. If you plan to use uv to install a global python/python3 or to install tools, see "Make uv-managed Python and tools available on the PATH" in the section below.

Verify uv installation

Confirm uv is installed and accessible:

$ uv --version
uv 0.7.2 (Homebrew 2026-03-20)

You should see a version number (yours may be newer). Homebrew builds often include (Homebrew ...) in the output, which confirms you are running the Homebrew-managed copy.

Check the path to the binary:

$ which uv
/opt/homebrew/bin/uv

If which uv shows ~/.local/bin/uv instead of the Homebrew path, you also have a standalone installation from the curl installer. The standalone copy may take priority depending on your PATH order. Decide which installation to keep and remove the other to avoid confusion.

If you see zsh: command not found: uv, the Homebrew bin directory may not be in your PATH. See Command not found: uv for troubleshooting.

Homebrew uv vs the official installer

There are two ways to install uv on Mac: Homebrew (brew install uv) and the official standalone installer (curl). They install the same program but differ in how they are managed.

  • Homebrew method: install with brew install uv, update with brew upgrade uv. Homebrew manages the binary in its own directory. Version updates depend on when Homebrew maintainers build new bottles, which can lag behind Astral's releases by a few days.
  • Official installer: install with curl -LsSf https://astral.sh/uv/install.sh | sh, update with uv self update. The binary lives in ~/.local/bin. Updates are immediate because uv updates itself directly from Astral.

Choose Homebrew if you already use it for other tools and want a consistent brew upgrade workflow. Choose the official installer if you want the latest releases immediately or do not use Homebrew.

You can check which version Homebrew has available:

$ brew info uv

Important: do not run uv self update if you installed uv with Homebrew. The self-update command will create a conflicting standalone installation. Always use brew upgrade uv for Homebrew-managed uv.

Install Python after installing uv

After installing uv, you can use it to install and manage Python versions. Install the latest stable Python:

$ uv python install

Verify that Python is available through uv:

$ uv run python --version

The tool uv manages its own Python installations separately from any Homebrew Python you may have installed with brew install python. There is no conflict between the two, but uv's managed Python takes priority when you use uv commands.

If you also have Homebrew Python installed, you can check which Python uv detects from the system:

$ uv python find --system

This shows the system or Homebrew Python that uv can see, separate from the versions uv manages itself. See Brew Install Python for more about Homebrew Python.

Make uv-managed Python and tools available on the PATH

Running Python through uv run always works without any extra setup. But uv can also install a global python and python3, and it can install command-line tools (with uv tool install or the uvx shortcut). Those executables are placed in ~/.local/bin, which is not the Homebrew bin directory and is not on your PATH by default, even though the uv command itself is.

Install a default global Python:

$ uv python install --default

This puts python and python3 in ~/.local/bin. Likewise, uv tool install ruff and uvx ruff place their tool binaries there. To run any of these directly, add ~/.local/bin to your PATH:

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

See the "Set the PATH for uv on Mac" section in Install uv on Mac for which shell configuration file to edit and how to apply the change. The uv binary's own location depends on how you installed it (Homebrew puts it in the Homebrew bin directory), but uv's managed Python and tools always go in ~/.local/bin regardless of the install method.

Update uv with Homebrew

Update Homebrew's package index first, then upgrade uv:

$ brew update
$ brew upgrade uv

Check if an update is available:

$ brew outdated uv

If you need to stay on a specific version of uv, you can pin it to prevent automatic upgrades:

$ brew pin uv

Remove the pin when you are ready to upgrade:

$ brew unpin uv

Enable shell autocompletion

You can set up tab completion for uv commands in Zsh. See the shell autocompletion section in Install uv on Mac for instructions.

Uninstall uv

To remove uv installed via Homebrew:

$ brew uninstall uv

If you want to clean up cached data before uninstalling:

$ uv cache clean

Troubleshooting Homebrew uv

If you run into problems after installing uv with Homebrew, check these common issues:

  • zsh: command not found: uv after installing: the Homebrew bin directory is not in your PATH. See Command not found: uv for step-by-step fixes.
  • Homebrew version is older than expected: Homebrew bottles can lag behind Astral's releases by a few days. Run brew update && brew upgrade uv to get the latest available version. If you need the newest release immediately, consider switching to the official installer. See Install uv on Mac.
  • Mixed installations causing confusion: if which uv points to ~/.local/bin/uv instead of the Homebrew path, you have both a standalone and a Homebrew install. Remove one with rm ~/.local/bin/uv ~/.local/bin/uvx (standalone) or brew uninstall uv (Homebrew) to avoid conflicts.

What's next

You have uv installed with Homebrew. See Install uv on Mac for the full usage guide, including how to start projects, manage dependencies, and run scripts with uv. See uv for Python on Mac for an overview of what uv replaces and how it compares with pyenv and pip.

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.