# pyenv: Python Version Manager


pyenv is a command-line tool for installing, managing, and switching between multiple Python interpreter versions on macOS and Linux. It intercepts Python commands through shell shims, routing them to whichever interpreter version is active for the current directory, user, or system.

## When to use pyenv

pyenv fits workflows where Python version management should remain separate from package management. It pairs with [pip](https://pydevtools.com/handbook/reference/pip.md), [venv](https://pydevtools.com/handbook/reference/venv.md), or any other packaging tool without imposing opinions on how dependencies are managed. If you want a single tool that also handles dependencies and virtual environments, [uv](https://pydevtools.com/handbook/reference/uv.md) covers version management alongside those workflows.

## Installation

Install with [Homebrew](https://pydevtools.com/handbook/reference/homebrew.md):

```bash
brew install pyenv
```

Or use the automatic installer:

```bash
curl https://pyenv.run | bash
```

After installation, add pyenv to your shell startup file (`.bashrc`, `.zshrc`, or `config.fish`):

```bash
eval "$(pyenv init -)"
```
pyenv does not support Windows natively. Use [pyenv-win](https://github.com/pyenv-win/pyenv-win) instead:

```powershell
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
```

Alternatively, [uv](https://pydevtools.com/handbook/reference/uv.md) provides cross-platform Python version management with the same commands on every OS.
## Key Commands

### Installing Python versions

pyenv compiles Python from source, which requires build dependencies but allows installing any CPython release, PyPy, or Anaconda/Miniconda distribution.

```bash
# List all available versions
pyenv install --list

# Install a specific version
pyenv install 3.12.4

# Uninstall a version
pyenv uninstall 3.12.4
```

### Switching versions

pyenv supports three scopes for version selection, each overriding the one below it:

```bash
# Set the version for the current shell session
pyenv shell 3.12.4

# Set the version for the current directory (writes a .python-version file)
pyenv local 3.12.4

# Set the default version for your user account
pyenv global 3.12.4
```

The [.python-version file](https://pydevtools.com/handbook/explanation/what-is-a-python-version-file.md) that `pyenv local` creates is also recognized by [uv](https://pydevtools.com/handbook/reference/uv.md), making migration straightforward.

### Inspecting the current state

```bash
# Show the active Python version and how it was selected
pyenv version

# List all installed versions
pyenv versions
```

## How shims work

pyenv inserts a directory of lightweight wrapper scripts (shims) at the front of your `PATH`. When you run `python`, the shim checks pyenv's configuration to determine which interpreter to forward the call to. This happens transparently; tools and editors that call `python` get the version pyenv selected without any changes on their end.

## Limitations

- macOS and Linux only. Windows requires the separately maintained [pyenv-win](https://github.com/pyenv-win/pyenv-win).
- Compiles from source. Installing a Python version requires C build tools and can take several minutes. Missing system libraries cause cryptic build failures.
- Version management only. pyenv does not handle virtual environments or dependencies. Use [pyenv-virtualenv](https://pydevtools.com/handbook/reference/pyenv-virtualenv.md) or a separate tool for environment management.

## Related Handbook Pages

- [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)
- [How to switch from pyenv to uv for managing Python versions](https://pydevtools.com/handbook/how-to/how-to-switch-from-pyenv-to-uv-for-managing-python-versions.md)
- [What is a .python-version file?](https://pydevtools.com/handbook/explanation/what-is-a-python-version-file.md)
- [pyenv-virtualenv](https://pydevtools.com/handbook/reference/pyenv-virtualenv.md) reference

## Learn More

- [pyenv on GitHub](https://github.com/pyenv/pyenv)
- [pyenv command reference](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md)
- [pyenv-win for Windows](https://github.com/pyenv-win/pyenv-win)