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

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

Create the new environment and reinstall from that list:

```bash
uv add -r requirements.txt
```
This records the packages as project dependencies and writes a [lockfile](https://pydevtools.com/handbook/explanation/what-is-a-lock-file.md). uv creates the `.venv/` automatically.
```bash
uv venv
uv pip install -r requirements.txt
```
This mirrors the old flat environment without a `pyproject.toml`.
{{< callout type="info" >}}
`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.
{{< /callout >}}

## 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](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.
- [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)