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 if Homebrew is configured correctly. Homebrew adds its bin directory to your PATH during its own installation. If Homebrew commands already work, uv will too.

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.

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.