Ditch pip and pyenv: Manage Your Entire Python Toolchain with uv

What You'll Build

You'll replace pip, pip-tools, and pyenv with a single tool called uv. By the end, you'll have a new Python project with a pinned Python version, a locked dependency graph, and a workflow that reproduces identically on any machine.

Prerequisites

• macOS, Linux, or Windows (WSL2 recommended on Windows)
• A terminal with shell access
• No existing Python installation required

The commands here use uv 0.4 or later. Run uv --version after install to confirm.

Step 1: Install uv

macOS and Linux:

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

This installs the uv binary to ~/.local/bin without sudo. You can read the script at that URL before running it.

macOS via Homebrew (alternative):

brew install uv

Windows (PowerShell):

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

After the curl or PowerShell install, open a new terminal so your PATH updates take effect. Then confirm:

uv --version

Step 2: Install Python

No pyenv, no python.org installer. uv downloads and manages Python versions directly:

uv python install 3.12

uv stores the build in its own cache directory and never touches your system Python. To see all installed versions:

uv python list

Step 3: Start a Project

uv init my-project
cd my-project

uv generates a minimal project scaffold:

To switch to a different Python version for this project:

uv python pin 3.11

That rewrites .python-version. uv reads this file automatically every time you work in the directory.

Step 4: Add a Dependency

uv add requests

One command does what used to take three steps. uv adds requests to pyproject.toml, creates uv.lock with every transitive dependency pinned, and installs everything into a local .venv. You never run pip install or python -m venv by hand.

For dev-only tools like test runners:

uv add --dev pytest

Step 5: Run Your Code

Use uv run instead of activating the virtual environment manually:

uv run python hello.py

uv run pytest

Before executing, uv run syncs the environment with uv.lock automatically, so the right packages are always present.

Step 6: Reproduce on Another Machine

Commit both pyproject.toml and uv.lock to version control. When a teammate clones the repo, they run:

uv sync

uv reads the lockfile and installs exact versions. To update all dependencies to their latest allowed versions:

uv lock --upgrade
uv sync

Verify It Works

uv run python -c "import requests; print(requests.__version__)"

You should see a version number like 2.32.3. Also confirm the lockfile and environment exist:

ls uv.lock
ls .venv/bin/python   # macOS/Linux

Troubleshooting

uv: command not found after install Open a new terminal. If that doesn't help, run source ~/.bashrc (bash) or source ~/.zshrc (zsh) to reload your PATH.

Wrong architecture on Apple Silicon (M1/M2/M3) If uv downloads an x86_64 Python build, your terminal may be running under Rosetta. Open a native arm64 terminal from Applications and retry uv python install 3.12.

uv add reports "No solution found" A version conflict exists between your dependencies. The error output names the conflicting packages. Try pinning a specific version with uv add package==1.2.3, or check whether the package supports your Python version in its metadata.

Migrating a project that has requirements.txt

uv add -r requirements.txt

This imports every entry into pyproject.toml and generates uv.lock.

Next Steps

• Inline scripts: uv can run a standalone Python file with its own declared dependencies using PEP 723 metadata and uv run script.py.
• Tool installs: replace pipx with uv tool install ruff to install CLI tools in isolated environments.
• CI/CD: use uv sync --frozen in pipelines to install exactly what the lockfile says without attempting any updates.
• Workspaces: manage a monorepo of related packages with uv's workspace feature, documented at docs.astral.sh/uv/concepts/workspaces.