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.tomldeclares project metadata, dependency requirements, and supported Python versions throughrequires-python.uv.lockrecords the resolved dependency versions, including transitive dependencies and platform-specific choices..python-versionrecords the default interpreter request, here3.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