Python

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

uv for Python on Mac

uv for Python on Mac. What uv is, what it replaces, and how to get started. The tool uv is an extremely fast Python package and project manager that replaces pip, pyenv, and virtualenv. Download and install uv on macOS.

The tool uv is an extremely fast Python package and project manager, written in Rust, developed by Astral (the company behind the Ruff linter). It replaces multiple separate Python tools with a single unified program: pip for package installation, pyenv for version management, virtualenv for environment isolation, and pipx for running CLI tools.

If you've managed Python on your Mac with a combination of pip, pyenv, virtualenv, and Homebrew, uv simplifies the entire workflow into one tool. If you're just getting started with Python, uv is the preferred tool for Python management (unless you are following older tutorials).

This article explains what uv does and how it compares with other Python tools. For installation instructions, see Install uv on Mac or Brew Install uv. For an overview and other ways to install Python, see Best Way to Install Python.

Setting up Python for software development is just part of setting up a Mac. See the checklist and visual roadmap to set up a Mac.

Before you get started

Setting up Python on a Mac requires a terminal application. 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's FREE and worth a try.

What is uv

The tool uv is a Python package and project manager that handles everything from installing Python itself to managing dependencies and running scripts. It was created by Charlie Marsh at Astral, the same company that developed Ruff, the fast Python linter and formatter.

The tool uv is written in Rust, which makes it 10-100x faster than pip for package installation and dependency resolution. Speed comes from parallel downloads, a global package cache, and an efficient resolver. Installing packages that took pip several seconds completes in under a second with uv.

Astral releases new versions of uv frequently (often weekly). The project is under active development with a growing community.

What uv replaces

Most Mac developers manage Python with several separate tools. The tool uv consolidates them into one program. Here is what uv replaces:

  • pyenv (version management) is replaced by uv python install and uv python pin. The tool uv downloads and manages Python versions directly. No shell shims are needed, unlike pyenv.
  • pip (package installation) is replaced by uv add for project dependencies and uv pip install for ad-hoc installations. The resolver is faster and handles conflicts better than pip.
  • virtualenv and venv (environment isolation) are replaced by automatic virtual environments. When you run uv init or uv sync, uv creates a .venv/ directory in your project automatically. No separate setup step is needed.
  • poetry (project management) is replaced by uv init, uv add, and uv lock. The tool uv uses the standard pyproject.toml format for project configuration.
  • pipx (running CLI tools) is replaced by uvx for ephemeral tool execution and uv tool install for permanent installations. See Install pipx on Mac if you still need pipx for other reasons.
  • pip-tools (requirements compilation) is replaced by uv pip compile for generating requirements.txt from requirements.in.

The key difference is that uv provides all these capabilities in a single program instead of requiring five or six separate tools that must be installed and configured individually. The availability of uv makes Python tooling much simpler and easier to manage.

Why uv for Python on Mac

For Mac developers setting up a Python environment, uv has several advantages.

One tool instead of many

Setting up Python on Mac traditionally requires installing Python, then pyenv, then pip, then virtualenv, then possibly poetry or pipx. Each tool has its own installation steps, configuration files, and update process. With uv, you install one tool and it handles everything.

Speed

The speed difference is noticeable in daily use. Running uv add requests completes in under a second. Resolving a complex dependency tree that takes pip 30 seconds finishes in 1-2 seconds with uv. The global cache means packages downloaded for one project are reused instantly in other projects.

Works with existing projects

The tool uv reads pyproject.toml, requirements.txt, and other standard Python project files. You can adopt uv incrementally without converting your entire workflow at once. Existing projects continue to work.

macOS is a first-class platform

The tool uv provides native binaries for both Apple Silicon (M-series) and Intel Macs. Installation is a single command on either architecture.

Install uv on Mac

There are two ways to install uv on Mac: the official installer (curl) and Homebrew (brew install uv). See Install uv on Mac for the full installation guide with PATH setup and a project walkthrough. See Brew Install uv for the Homebrew-specific guide, including how it differs from the official installer and how to update safely.

After installing, confirm uv is working with uv --version. If you see zsh: command not found: uv, see Command not found: uv for troubleshooting.

uv vs pyenv

Both uv and pyenv manage Python versions, but they work differently.

The tool uv downloads pre-built Python binaries and manages them in ~/.local/share/uv/python/. There are no shell shims or init scripts. Python versions are available instantly through uv commands such as uv run and uv python pin.

Pyenv compiles Python from source (or downloads pre-built binaries with pyenv-install) and uses shell shims to intercept the python command. It requires adding eval "$(pyenv init -)" to your shell configuration.

Use uv if you want a faster, simpler tool that also handles packages and environments. Use pyenv if your team or workplace requires it, or if you are following a course that assumes pyenv. The tool uv can coexist with pyenv on the same Mac if needed.

The command uv python pin 3.12 creates a .python-version file in the project directory, the same file format that pyenv uses. This makes migration straightforward because both tools recognize the file.

To migrate from pyenv to uv:

  1. Install uv alongside pyenv using the official installer or Homebrew.
  2. Use uv python install 3.12 to install the same Python versions you use with pyenv.
  3. In each project, add or update a pyproject.toml file and start using uv add instead of pip install.
  4. After all active projects use uv workflows, remove pyenv if you no longer need it.

uv vs pip

Pip remains Python's official package installer and is included with every Python installation. The tool uv provides a compatible interface (uv pip install, uv pip freeze) that is faster.

The main difference: pip installs packages globally or into a manually created virtual environment. The tool uv manages virtual environments automatically per project. When you use uv add to install a package, uv creates the environment, installs the package, and records the dependency in pyproject.toml.

If you are following tutorials that use pip commands, uv's uv pip install works as a drop-in replacement. For new projects, uv add is the recommended approach.

Core uv workflows

Here is a summary of common uv commands.

Manage Python versions

$ uv python install 3.12
$ uv python list --only-installed
$ uv python pin 3.12

Start a project

$ uv init myproject
$ cd myproject
$ uv add requests
$ uv run python script.py

Run tools

$ uvx ruff check .
$ uv tool install ruff

Create a lock file

$ uv lock

The command uv lock generates a lock file that records exact dependency versions. This ensures reproducible installs across machines and CI environments. The lock file is committed to version control alongside pyproject.toml.

For a full walkthrough of these workflows, see Install uv on Mac.

Where to go next

This page covers what uv is and why to use it. Here are the guides for specific tasks:

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.