Python

audience developer
level all
topic Python
subtopic Installation

Install Python with UV

How to install Python with UV on Mac. UV for Python version, environment, and package management. UV, an extremely fast all-in-one tool for Python development.

Python is often the first programming language you'll install on a Mac. Until recently, a lack of standard development tooling made setting up Python complicated. See the article Mac Python for a comparison of all prominent Python installation methods for macOS -- from UV and Pyenv to Homebrew and the official installer.

This guide covers UV, the emerging favorite for installing and managing Python on macOS. UV provides an all-in-one approach that's 10-100x faster than previous tools, simplifying Python development whether you're working with single scripts or complex programming projects.

Before you get started

You'll need a terminal application to install and use Python. Apple includes the Mac terminal but I prefer Warp Terminal. Warp increases developer productivity, helping you remember easily-forgotten commands and adds AI troubleshooting. Download Warp Terminal now; it's FREE and worth a try.

Why UV?

UV streamlines Python development by offering a single coherent setup and packaging system, eliminating the need for separate tools such as pip, pip-tools, pipx, poetry, pyenv, or virtualenv. For any project more complex than a simple script, use UV to install Python and software libraries. UV is extremely fast (10-100x faster than pip), making your workflow more efficient.

Comparing UV and other Python tools

UV and other Python tools differ in their approach to Python's historical limitations:

  • Traditional Python took a system-wide approach with global installations and limited isolation, leading to "works on my machine" problems, dependency conflicts, and difficult onboarding. Pyenv was introduced as an add-on for version management, Venv or Virtualenv for virtual environments, and Pip for installing packages.

  • Working with UV is similar in approach to newer languages like Ruby and JavaScript, where projects are isolated in directories with version management, virtual environments, and package installation handled by a single unified tool. For an explanation of the role of version management, virtual environments, and package installation in Python, see my Mac Python general guide.

This difference means that UV is simpler to use for developers who have experience with other languages, while Pyenv and other tools fit in the established Python ecosystem that some people expect.

Steps

There is no need to install Homebrew or Python before installing UV. Install the UV tool from the command line. UV will install the newest Python automatically. You can then install additional Python versions.

Here's how to install UV:

  1. Check macOS and update macOS.
  2. Check if Xcode Command Line Tools are installed.
  3. Install UV with a self-install script (it will install the latest Python).
  4. Set the Mac PATH for Python to make sure you use the correct version of Python.

Xcode Command Line Tools are required before installing Python (or any other programming language) because UV needs the basic Unix utilities that are not included by default in the macOS.

The Mac Path is an environment variable that controls where the operating system looks for executables. Setting the Mac PATH for Python is crucial because macOS will have multiple Python versions installed. Your PATH determines which version runs when you type python or python3. UV updates the PATH automatically, but it's crucial to understand and check the PATH for troubleshooting.

Check for Python

You'll need Xcode Command Line Tools for software development, and with Xcode CLT, Apple includes Python 3.9.6. As of October 2024, the latest Python version is 3.13.

You should not attempt to update or remove the system Python installed with Xcode Command Line Tools. Just install a newer Python version with UV.

Install UV with Homebrew

It's easiest to install UV directly with the curl command (below) but if you prefer, you can install UV with Homebrew.

$ brew install uv

When you install UV with Homebrew, you will need to set the PATH environment variable for UV (see below). Instead, if you install UV directly with the curl command, it will modify your shell configuration files for you.

Install UV with curl

You can install UV with a curl command.

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

Curl is a command-line tool that makes HTTP requests from the terminal, useful for tasks like downloading and running installation scripts.

The installer will download and install the UV binary. If you'd like to see the available options before running the installer, you can view the help information:

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

By default, UV is installed to ~/.local/bin. If you want to change the installation path, you can use the UV_INSTALL_DIR environment variable:

$ curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/custom/path" sh

The installer will run its own utility to modify your shell ~/.zshenv configuration file to ensure UV and its Python versions are on your PATH. If you don't want this behavior, you can disable it:

$ curl -LsSf https://astral.sh/uv/install.sh | env INSTALLER_NO_MODIFY_PATH=1 sh

Many developers prefer to set the PATH in the ~/.zprofile shell configuration file, rather than the ~/.zshenv file. If that's your preference, disable the automatic behavior and set the PATH manually.

Set the $PATH for UV

If you want to set the PATH manually, or you've installed UV using Homebrew, you must set the Mac PATH to make sure UV is available on the commnd line. Otherwise, entering the command python will trigger zsh: command not found: python and the command python3 will access the older Xcode-installed Python version.

You have two options to set the $PATH for UV.

  • Use the UV uv tool update-shell command to set the $PATH in ~/.zshenv
  • Set the $PATH manually in ~/.zprofile

Use the UV uv tool update-shell command

UV provides a utility command to set the $PATH in ~/.zshenv:

$ uv tool update-shell

This is the command that runs automatically during the curl installation process to set the $PATH for UV but you can run it yourself if you installed UV with Homebrew.

This adds the following line to ~/.zshenv:

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

Many developers prefer to set the $PATH in the ~/.zprofile file, not ~/.zshenv, so you may want to set the $PATH manually.

Set the $PATH manually

You can use TextEdit, the default macOS graphical text editor, to edit the ~/.zprofile file. Alternatively, you can edit the ~/.zshrc file. It works the same but, by convention and design, the ~/.zprofile file is used for setting the $PATH (see .zshrc or .zprofile for an explanation). You can open a file in TextEdit from the terminal:

$ open -e ~/.zprofile

You also can use the command line editors nano or vim to edit the shell configuration files. See Shell Configuration for more about editing shell configuration files.

Add this command as the last line of your configuration file to configure the Zsh shell for UV.

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

Changes to the ~/.zprofile file will not take effect in the Terminal until you've quit and restarted the terminal. Alternatively (this is easier), you can use the source command to reset the shell environment:

$ source ~/.zprofile # Or just restart your terminal

The source command reads and executes a shell script file, in this case resetting the shell environment with your new $PATH setting.

After resetting your shell, you can check the $PATH setting.

$ echo $PATH
~/.local/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin

The ~/.local/bin directory will be leftmost, taking precedence over other directories. If you've used the uv tool update-shell command, the ~/.local/bin directory will be rightmost, with the lowest precedence.

Verify UV installation

After installing UV, use uv --version to verify that it has been installed.

$ uv --version
uv 0.6.14

If you don't see this output, make sure that the UV installation directory is in your PATH. You may need to restart your terminal or source your shell configuration file.

Install Python with UV

One of UV's features is its ability to install and manage Python versions. To install the latest Python version:

$ uv python install --preview

As of this writing, the --preview flag is necessary to install a Python executable into ~/.local/bin so that it is available from the command line.

To install a specific Python version:

$ uv python install 3.12 --preview

You can remove Python versions:

$ uv python uninstall 3.13

Verify Python installation

After installing Python with UV, you can find which Python versions are installed:

$ uv python find

UV provides a command to show which directory contains the Python executables:

$ uv python dir

When using UV commands, the appropriate Python version will be automatically selected. If you want to directly use Python, you can rely on UV's automatic Python downloads. For example:

$ uvx [email protected] -c "print('hello world')"

This will automatically download Python 3.13 if it's not already installed.

Use UV

You can use UV to:

  1. Install and manage Python versions.
  2. Set up a Python project with package dependencies.
  3. Run Python scripts.
  4. Run Python tools.
  5. Install Python packages.

1. Managing Python versions

# Install Python versions
$ uv python install 3.11 3.12

# List available and installed versions
$ uv python list

# Pin a project to a specific Python version
$ uv python pin 3.11

You can check if a Python version is availble:

$ python --version

You can check where Python versions are installed:

$ which -a python
/Users/daniel/.local/bin/python

2. Working with projects

# Create a new project
$ uv init myproject

# Add dependencies
$ uv add requests

# Sync dependencies with the environment
$ uv sync

# Lock dependencies
$ uv lock

# Run commands in the project environment
$ uv run python script.py

Here uv init myproject creates both the directory structure and the pyproject.toml file so you can add a library (requests in this example).

With uv init myproject, UV automatically handles Python virtual environments -- isolated spaces that keep project dependencies separate from each other. This is crucial for managing multiple Python projects without package conflicts. For a more detailed explanation of virtual environments, lock files, and why they matter, see my Mac Python general guide.

If you are following a tutorial that uses pip to install packages, you can choose to use UV's add command. Or use UV's drop-in replacement for pip, the Python package installer, like this:

# Create a virtual environment
$ uv venv

# Install packages
$ uv pip install requests

# Compile requirements
$ uv pip compile requirements.in -o requirements.txt

3. Managing scripts

# Run a script with dependencies
$ uv run script.py

# Add dependencies to a script
$ uv add --script script.py requests

4. Working with tools

# Run a tool in an ephemeral environment
$ uvx ruff check .

# Install a tool
$ uv tool install ruff

Shell autocompletion

To enable shell autocompletion for UV commands in the Zsh shell:

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

Then restart your shell or source the configuration file.

Updating UV

When UV is installed via the standalone installer, it can update itself on-demand:

$ uv self update

If you installed UV using Homebrew, you can update it using the following command:

$ brew upgrade uv

Uninstall UV

If you decide you don't want to use UV anymore, you can remove it:

  1. Clean up stored data (optional):
$ uv cache clean
$ rm -r "$(uv python dir)"
$ rm -r "$(uv tool dir)"
  1. Remove the UV binaries:
$ rm ~/.local/bin/uv ~/.local/bin/uvx
  1. If the installer modified your shell profiles, you'll need to edit those files to remove any UV-related lines.

What's next

Now that you have UV installed, you can start using it for all your Python development needs. UV simplifies Python development by providing a single tool for managing versions, packages, and projects.

My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.