Choose by the job you need to do
Use pyenv when your main requirement is selecting among Python interpreters, especially in an existing pyenv workflow. Use uv when you also want one tool to manage a project’s interpreter, isolated environment, dependencies, and lockfile.
Both can select a Python version. The larger difference is how much of the project workflow they manage.
How pyenv selects Python
pyenv places shims on PATH and resolves a command such as python to the chosen interpreter. Selection normally follows this order: the PYENV_VERSION environment variable, a .python-version file in the current directory or its parents, and the global setting.
pyenv versions
pyenv local 3.12.8
python --version
The example requires that version to be installed. It demonstrates a project selection, not a recommendation to use that particular patch release today. Use a supported patch release appropriate to your project.
A selected interpreter is not an isolated dependency environment. Standard python -m venv or the separate pyenv-virtualenv plugin can provide that layer. Base pyenv does not supply a dependency resolver or lockfile.
What uv manages
uv is a Python package and project manager written in Rust by Astral. It can install supported Python builds, create environments, resolve dependencies, and run commands within a project.
Its project workflow connects pyproject.toml, uv.lock, and a local .venv. A .python-version file can pin the requested interpreter; it is distinct from the project’s requires-python compatibility range. See uv’s Python version documentation.
Install without mixing shell setup instructions
For pyenv, follow the official installation and shell setup instructions. Linux source builds need system libraries, and shell initialization differs between Bash and Zsh. On Windows, check the project’s platform guidance rather than assuming Unix shell instructions work unchanged.
For uv, choose an installer from the official installation guide. After installation, confirm which executables your shell finds:
command -v python
python --version
uv --version
These checks help diagnose a common problem: installing a new tool does not necessarily change the interpreter already selected by your shell or editor.
Keep an existing pyenv project
If a project already uses pyenv, there is no need to migrate solely to change a version selector. Once the intended Python is selected, create an isolated environment:
python -m venv .venv
source .venv/bin/activate
python -m pip --version
This activation example is for a POSIX shell. Use the platform-specific activation command on Windows. Install dependencies using the project’s existing requirements or packaging workflow.
Start a uv project
In a new directory:
uv init --python 3.12
uv add requests
uv run python --version
uv run python -c 'import requests; print(requests.__version__)'
Here, 3.12 is an example minor version, not a claim that it is the latest Python. uv init creates project metadata and starter files; it does not discover and install every import in existing source code. uv add declares a dependency. Project commands such as uv run or uv sync create or update .venv as needed.
Reproduce the dependency environment
Commit pyproject.toml and uv.lock. In a checkout with an up-to-date lockfile:
uv sync --locked
uv run --locked python --version
--locked rejects a lockfile that needs updating. Keep .venv out of version control and rebuild it from project metadata. Use uv lock when you intentionally update dependency resolution. The project guide explains these operations.
There is no uv install step in this workflow, and a uv shell command is not needed. Use uv run for project commands, or activate .venv with your shell’s normal activation mechanism.
Feature comparison
| Requirement | pyenv | uv |
|---|---|---|
| Select a Python interpreter | Shims and version selections | Python discovery, requests and project pins |
| Install Python | Commonly builds via python-build | Managed Python installations |
| Isolate project packages | Use venv or another tool/plugin | Project .venv or uv venv |
| Resolve and lock dependencies | Use a separate packaging tool | uv add, uv lock, uv sync |
| Run inside a project environment | Activate the environment | uv run |
The uv environment reference distinguishes its pip-compatible interface from its project interface. Avoid switching between them casually if you expect the lockfile to describe every installed dependency.
Where each approach fits
An established test matrix, shell convention, or build-from-source requirement may favor keeping pyenv. A new application with declared dependencies and repeatable local and CI setup is a good candidate for uv’s project workflow.
The two can coexist, but make interpreter selection explicit. Check uv run python --version rather than assuming it matches an unrelated python command outside the project environment.
Compare performance fairly
Installing an interpreter from source and synchronizing cached wheels measure different operations. Network access, cache state, available wheels, platform, and dependency graph all affect timings. This article does not provide a controlled benchmark, so it does not claim that one entire workflow is a fixed number of times faster.
Tradeoffs to check before changing tools
pyenv keeps interpreter selection separate from packaging, which fits teams with an established dependency tool. That also means more pieces to document. uv combines those tasks, but the team must agree on lockfile updates, interpreter requirements, and CI commands.
Check native extension availability and deployment constraints before changing the Python minor version. A lockfile improves reproducibility; it cannot make an unsupported operating system or Python version compatible with a package.
A migration checklist
- Record the current Python version, dependency files, test command, and deployment environment.
- Try uv in a separate branch or disposable checkout. Declare dependencies explicitly rather than copying an old virtual environment.
- Compare application tests and behavior using the intended interpreter.
- Update local setup and CI together, then commit the metadata and lockfile.
Keep pyenv if version selection is all you need. Adopt uv when its project workflow removes a real maintenance burden. Tool syntax and references were reviewed on October 16, 2026; the examples are separate from a migration acceptance test for your application.