How do I switch from pyenv to uv?

Remove pyenv's shell initialization (`eval "$(pyenv init -)"` lines in `.bashrc` or `.zshrc`), uninstall pyenv with `rm -rf ~/.pyenv` or `brew uninstall pyenv`, then install uv and replace pyenv commands with their uv equivalents: `uv python install 3.12` for `pyenv install`, `uv python pin 3.12` for `pyenv local`, and `uv python list` for `pyenv versions`.

Do I need to install Python versions manually with uv?

No. uv downloads required Python versions on demand when a command needs them, so explicit `uv python install` calls are optional. Run `uv python install` only when you want a version available offline. This is the main behavioral difference from pyenv, which requires installing each interpreter before use.

Does uv respect .python-version files from pyenv?

Yes. uv reads `.python-version` files the same way pyenv does, so committed pin files keep working after the switch. Use `uv python pin 3.12` to write or update one. The file is the recommended way to lock a project's Python version, and both tools honor it during their respective workflows.

Will my pyenv-managed virtualenvs still work after switching to uv?

No, but you can move their packages. pyenv-virtualenv environments depend on pyenv's shims and stop working once pyenv is uninstalled. Before deleting each one, run `pip freeze > requirements.txt` from inside it to capture the installed packages. Then recreate the environment with uv and reinstall: `uv add -r requirements.txt` for a project, or `uv venv` followed by `uv pip install -r requirements.txt` for a standalone venv. uv manages the project venv at `.venv/` in the project root by default.

How to switch from pyenv to uv for managing Python versions

by Tim Hopper · Markdown

uv Virtual Environments

This guide shows how to transition from using pyenv to uv for managing Python versions. While pyenv has been a reliable tool for many years, uv offers faster performance and more integrated workflows.

Steps to Switch

1. Remove pyenv Integration From Shell

Remove pyenv initialization from your shell configuration files:

Open your shell configuration file (.bashrc, .zshrc, etc.)
Remove or comment out lines like:

eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Reload your shell configuration:

source ~/.bashrc  # or .zshrc, etc.

2. Clean Up pyenv Installation

Remove pyenv from your system:

# Remove pyenv versions and configuration
rm -rf ~/.pyenv

# Or if installed via package manager
brew uninstall pyenv  # macOS

3. Transition to uv’s Python Management

Instead of pyenv commands, you’ll now use uv’s equivalents:

Replace pyenv install 3.12 with uv python install 3.12
Replace pyenv versions with uv python list
Replace pyenv local 3.12 with uv python pin 3.12

Unlike pyenv, uv will automatically download and install required Python versions when they’re needed. You don’t need to explicitly install versions unless you want them available offline.

4. Move Each Environment’s Packages to uv

pyenv-managed environments stop working once pyenv is gone, so recreate each one with uv. Export the installed packages first, or you’ll lose them.

Capture the current packages while the old environment still exists:

# Activate the old pyenv environment, then:
pip freeze > requirements.txt

Create the new environment and reinstall from that list:

uv add -r requirements.txt

This records the packages as project dependencies and writes a lockfile. uv creates the .venv/ automatically.

pip freeze pins every package, including transitive dependencies, so uv add -r requirements.txt adds those sub-dependencies as top-level entries. For a cleaner pyproject.toml, run uv add with only the packages you import directly (uv add requests flask) and let uv resolve the rest.

Adjusting Your Workflow

Key differences to note:

Virtual environments are typically managed automatically by uv when running commands
Python versions are downloaded on-demand rather than requiring explicit installation
The .python-version file is still supported for version pinning

Learn More

uv: A Complete Guide covers what uv does, how fast it is, the core workflows, and recent releases.
What is a .python-version file?
How to add Python to your system path with uv
How do pyenv and uv compare for Python interpreter management?

Last updated on July 8, 2026

How to stop AI agents from bypassing pre-commit hooks How to test a Python library against multiple type checkers

Please submit corrections and feedback...