Install Python with uv

macOS and most Linux distros ship a system Python you should leave alone — it belongs to the OS, and pip install against it will eventually break something the OS depends on. Use uv instead. It installs Python versions on demand, manages per-project virtual envs, and replaces pip, pip-tools, pyenv, virtualenv, and poetry with a single binary written in Rust. This post covers installing uv itself and using it to install Python.

macOS and Linux

The official installer is a single shell command. It drops uv into ~/.local/bin.

# install uv via the official script

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

On macOS you can also use Homebrew:

# install uv via homebrew

brew install uv

If you don't have Homebrew yet, see Install Homebrew.

Windows

Use the PowerShell installer or winget.

# install uv via the official script on windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# install uv via winget

winget install --id=astral-sh.uv -e

Install a Python version with uv

Don't brew install python or download the official .pkg. Let uv manage Python versions the same way fnm manages Node versions.

# list python versions uv can install

uv python list

# install python 3.12

uv python install 3.12

For a new project, pin the version in a virtual env:

# create a project with python 3.12

uv init my-project --python 3.12 && cd my-project

# add a dependency, like the anthropic sdk

uv add anthropic

uv writes a pyproject.toml and a lockfile, and creates .venv/ automatically. To run code inside the env:

# run a script using the project's venv

uv run python script.py

Verify

# check uv version and installed pythons

uv --version && uv python list --only-installed

You should see uv 0.4+ and at least one Python listed.

Common gotchas

• Don't mix pip install and uv add: pick one per project. uv add writes to pyproject.toml; pip install doesn't, so dependencies installed that way disappear on a clean rebuild.
• Global tools: install command-line Python tools with uv tool install <pkg> (e.g. ruff, pre-commit). It puts them on PATH without polluting any project venv.
• Activating venvs: you usually don't need to. uv run handles it. If a tool insists on source .venv/bin/activate, that still works.
• requirements.txt projects: uv pip install -r requirements.txt works as a drop-in for legacy projects you don't want to migrate yet.

With uv installed you can skip every other Python install guide on the internet — uv python install <version> covers all of them.