uv is a Python package and project manager that can also install Python itself. Written in Rust by Astral, it combines dependency installation, virtual environments, Python version management, and project locking in one command-line tool. See the uv documentation.

Which part does each tool manage?

There are three separate things to manage: the Python interpreter, an environment containing installed packages, and the project's dependency declarations.

Tool Main responsibility Example
pyenv Install Python versions and select which interpreter commands use pyenv local 3.13
venv Create an isolated package environment from an existing interpreter python -m venv .venv
pip Resolve and install packages into a Python environment python -m pip install httpx
uv Manage interpreters, environments, packages, and project dependencies uv add httpx

These responsibilities explain why a project might traditionally use pyenv + venv + pip together. pip does dependency resolution, but managing the interpreter, creating environments, and coordinating the whole project are outside pip's scope.

uv has two useful workflows

Keep an existing requirements.txt workflow

In a directory with requirements.txt and no other virtual environment active:

uv venv
uv pip install -r requirements.txt

uv venv creates .venv; uv pip install discovers it without requiring shell activation. You can also point uv at an existing environment. Environment documentation

Despite its name, uv pip runs uv's own implementation, rather than invoking pip. It supports familiar commands, but compatibility is not exact: for example, uv does not read pip.conf or PIP_INDEX_URL. Private indexes need uv's configuration. Compatibility guide

Let uv manage the project

After installing uv, create a small application using Python 3.13:

uv init --no-package --python 3.13 uv-demo
cd uv-demo
uv add httpx
uv run python -c "import httpx; print(httpx.__version__)"

--no-package creates an application without configuring it for installation as a Python package. uv can download a suitable interpreter if one is missing. uv add records the dependency, updates the lockfile, and installs it into the project environment. uv run prepares that environment and runs the command inside it, so activation is optional. Project guide

The important files have different jobs:

  • pyproject.toml declares project metadata, dependency requirements, and supported Python versions through requires-python.
  • uv.lock records the resolved dependency versions, including transitive dependencies and platform-specific choices.
  • .python-version records the default interpreter request, here 3.13. This selects the 3.13 series; use a full version when you need a particular patch release.
  • .venv/ contains the local environment and installed packages.

Commit the project metadata, lockfile, and shared interpreter pin; recreate .venv on each machine. The lockfile captures dependency choices across supported environments, rather than copying one machine's environment directory. Project files and Python version requests

For an existing checkout, synchronize its environment while requiring the committed lockfile to be current:

uv sync --locked

--locked fails if the lockfile is missing or needs updating. By default, uv sync also removes packages outside the selected dependencies. This is why uv pip install and uv add are different: the former changes an environment; the latter records a project dependency that future syncs preserve. Locking and syncing

How is uv different from pyenv?

pyenv specializes in interpreter selection. Its shims are small executables on PATH that route commands such as python to the selected installation. pyenv local makes that selection directory-specific. Most Python releases installed by pyenv are built from source, which also allows custom build options. Virtual-environment management is available through the separate pyenv-virtualenv plugin. pyenv documentation

uv can install and request an interpreter too:

uv python install 3.13
uv python pin 3.13
uv run python --version

uv's managed CPython installations use prebuilt distributions from Astral's python-build-standalone project. Pinning writes .python-version for uv's interpreter selection; uv does not install pyenv-style shims to switch a bare python command whenever you change directories. Use uv run or activate the environment to run its Python. Installing Python and version selection

The tools can coexist: uv can use an interpreter installed by pyenv. You can keep pyenv for interpreter builds and shell selection while using uv for dependencies and project environments.

Which should I use?

Use pip with venv when an existing installation workflow meets your needs. Consider uv when you want one tool to coordinate dependencies, environments, lockfiles, and Python versions. Keep pyenv when its shell switching or custom interpreter builds are useful. Choose based on the tasks you need to manage; adopting uv does not require replacing every part of an existing setup at once.

Comments

— comments

Reading Time

~3 min read

Published

Category

Tags

Stay in Touch