pyenv is a command-line tool that lets you install and switch between multiple Python interpreter versions on macOS and Linux. It uses shell shims to intercept Python commands and route them to the selected version.

Does pyenv work on Windows?

pyenv was designed for Unix-like systems. Windows users need pyenv-win, a separate community project that reimplements pyenv's functionality in PowerShell. Alternatively, uv provides cross-platform Python version management.

pyenv: Python Version Manager

by Tim Hopper

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, venv, 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 covers version management alongside those workflows.

Installation

Install with Homebrew:

brew install pyenv

Or use the automatic installer:

curl https://pyenv.run | bash

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

eval "$(pyenv init -)"

pyenv does not support Windows natively. Use pyenv-win instead:

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

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

# 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 that pyenv local creates is also recognized by uv, making migration straightforward.

Inspecting the current state

# 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.
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 or a separate tool for environment management.

Related Handbook Pages

Learn More

Also Mentioned In

Was this helpful?

Get Python tooling updates

Subscribe to the newsletter

Last updated on March 28, 2026

prek pyenv-virtualenv

Please submit corrections and feedback...