# How to switch from pyenv to uv for managing Python versions

This guide shows how to transition from using [pyenv](https://pydevtools.com/handbook/reference/pyenv.md) to [uv](https://pydevtools.com/handbook/reference/uv.md) 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:
```bash
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
```
3. Reload your shell configuration:
```bash
source ~/.bashrc  # or .zshrc, etc.
```

### 2. Clean Up pyenv Installation

Remove pyenv from your system:

```bash
# 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`

{{< callout type="info" >}}
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.
{{< /callout >}}

### 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:
```bash
uv venv
```

## 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

- [What is a .python-version file?](https://pydevtools.com/handbook/explanation/what-is-a-python-version-file.md)
- [How to add Python to your system path with uv](https://pydevtools.com/handbook/how-to/how-to-add-python-to-your-system-path-with-uv.md)
- [How do pyenv and uv compare for Python interpreter management?](https://pydevtools.com/handbook/explanation/how-do-pyenv-and-uv-compare-for-python-interpreter-management.md)