How to switch from pyenv to uv for managing Python versions

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:

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

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

3. 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

4. Recreate Virtual Environments

Since pyenv-managed environments will no longer work, you’ll need to recreate virtual environments for your projects:

1. Navigate to each project directory
2. Delete the old virtual environment if present
3. Create a new environment using uv:

uv venv

Adjusting Your Workflow

Key differences to note:

• Python versions aren’t globally available - use uv run or activated virtual environments
• 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