Python

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

Command not found: uv

How to fix command not found uv on Mac. You will see the command not found uv error when uv is not installed or the Mac PATH is not set correctly. How to fix the Mac PATH for uv.

The tool uv from Astral is a fast, all-in-one Python manager that combines version management, package installation, and virtual environments into a single command-line program. This guide explains why your Mac cannot find the uv command and how to fix it. See uv for Python on Mac for a full overview.

You might encounter the error zsh: command not found: uv when trying to run uv in the terminal. This error means the Zsh shell cannot find a program called uv in any directory listed in your PATH. Either uv is not installed, or it is installed but not in a directory the shell knows about.

This is the error you will see:

$ uv --version
zsh: command not found: uv

If you see an error that begins with bash: you are using the Bash shell. You likely have an older version of macOS. Check macOS and upgrade macOS to switch to the Zsh shell.

Installing Python tools is part of setting up your Mac for development. See the full roadmap to set up a Mac for software development.

Before you get started

You will need a terminal application to fix the error. 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.

Quick fix summary

If you are an experienced developer, a quick overview may be all you need. Check if uv is installed, fix the PATH if needed, and restart your terminal:

  1. Check if uv exists: ls ~/.local/bin/uv or brew list uv
  2. If uv is installed but not found: add export PATH="$HOME/.local/bin:$PATH" to ~/.zprofile
  3. Restart your terminal or run source ~/.zprofile
  4. Verify: uv --version

If the quick fix is not sufficient, read on for detailed troubleshooting.

Check if uv is installed

Before fixing the PATH, determine whether uv is actually installed on your Mac. Run these diagnostic commands:

$ which -a uv

If which returns a path (such as /Users/you/.local/bin/uv), uv is installed but your current shell session cannot find it. Skip ahead to the PATH fix section below.

If which returns nothing, check the default install locations manually:

$ ls ~/.local/bin/uv

This is where the official installer places uv. If the file exists, uv is installed and the problem is your PATH.

Check if uv was installed with Homebrew:

$ brew list uv

If Homebrew confirms uv is installed, the problem is your Homebrew PATH configuration. See Zsh: command not found: brew if the brew command itself is not found.

Check the old install location

Versions of uv before 0.5.0 installed to ~/.cargo/bin instead of ~/.local/bin. If you installed uv several months ago, the binary may be in the old location:

$ ls ~/.cargo/bin/uv

If the file is there, you have an outdated PATH configuration. The simplest fix is to reinstall uv with the current installer, which uses ~/.local/bin.

Inspect your PATH

If the diagnostics above are still unclear, print each PATH directory on its own line to see what your shell is searching:

$ echo $PATH | tr ':' '\n'

Look for ~/.local/bin (official curl installer), /opt/homebrew/bin (Homebrew on Apple Silicon), or /usr/local/bin (Homebrew on Intel). If the directory that contains uv is missing from this list, PATH is the root cause.

If uv is not installed

If none of the checks above found uv on your Mac, install it now. The recommended method is the official installer:

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

This installs uv to ~/.local/bin and updates your shell configuration automatically. See Install uv on Mac for the full installation guide.

Alternatively, install with Homebrew:

$ brew install uv

See Brew Install uv for the Homebrew installation guide.

Fix the PATH for uv on Mac

If uv is installed but not found, the PATH does not include the directory containing the uv binary. The fix depends on how you installed uv.

Installed via the official installer

Add ~/.local/bin to your PATH. Open your ~/.zprofile file. 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. Alternatively, use the uv tool update-shell command to set the PATH automatically:

$ ~/.local/bin/uv tool update-shell

Note the full path ~/.local/bin/uv in the command above. Since uv is not yet in your PATH, you must specify the full path to run it.

Installed via Homebrew on Apple Silicon (M-series)

Homebrew on Apple Silicon (M-series) Macs installs programs to /opt/homebrew/bin. If this directory is not in your PATH, no Homebrew programs will work (not just uv). See Zsh: command not found: brew for the Homebrew PATH fix.

Installed via Homebrew on Intel

Homebrew on Intel Macs installs programs to /usr/local/bin. This directory is usually in the PATH by default. If uv is not found after a Homebrew install on Intel, try restarting your terminal.

Which file to edit

On macOS, Zsh reads several configuration files. The ~/.zprofile file runs for login shells, which is what a terminal application opens by default. The ~/.zshrc file runs for interactive shells. Either file works for setting the PATH. See .zshrc or .zprofile for details.

Restart your terminal

After installing uv or changing your PATH, you must start a new shell session for the changes to take effect. You have several options:

Open a new terminal window. This is the simplest approach. The new window reads your updated configuration files.

Alternatively, reload the configuration file you modified:

$ source ~/.zprofile

This re-reads the file in your current session without opening a new window.

If the official installer created the file $HOME/.local/bin/env, you can source it as a shortcut that sets up PATH immediately in your current session:

$ source $HOME/.local/bin/env

Verify the fix

Confirm that the shell can now find uv:

$ uv --version
uv 0.7.2

You should see a version number (yours may be newer). Check the path to the uv binary:

$ which uv
/Users/you/.local/bin/uv

The path will be /opt/homebrew/bin/uv if you installed with Homebrew on Apple Silicon (M-series).

If uv still does not work

If the error persists after fixing your PATH and restarting, try a full reinstall.

For the official curl installer, remove the old binaries and reinstall:

$ rm ~/.local/bin/uv ~/.local/bin/uvx
$ curl -LsSf https://astral.sh/uv/install.sh | sh

For Homebrew, uninstall and reinstall:

$ brew uninstall uv
$ brew install uv

Check for multiple installations that may conflict:

$ which -a uv

If which -a uv lists more than one path, the first entry is the one your shell uses. Remove the installation you do not want, or adjust PATH order so the preferred copy comes first.

See Install uv on Mac or Brew Install uv for a full installation guide. See uv for Python on Mac for an overview of uv and how it compares with other Python tools.

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.