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:
- Check macOS and update macOS.
- Check if Xcode Command Line Tools are installed.
- Install UV with a self-install script (it will install the latest Python).
- 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:
- Install and manage Python versions.
- Set up a Python project with package dependencies.
- Run Python scripts.
- Run Python tools.
- 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:
- Clean up stored data (optional):
$ uv cache clean
$ rm -r "$(uv python dir)"
$ rm -r "$(uv tool dir)"
- Remove the UV binaries:
$ rm ~/.local/bin/uv ~/.local/bin/uvx
- 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.