Getting started

Introduction

pyenv installs Python versions, selects them per project, and exposes their commands through shims.

Install

curl -fsSL https://pyenv.run | bash
brew install pyenv
git clone https://github.com/pyenv/\
pyenv.git ~/.pyenv

The pyenv.run installer bundles pyenv-doctor, pyenv-update, and pyenv-virtualenv; Homebrew and a Git checkout work too. Most Python versions are built from source.

See: Installation, Build dependencies

Set up the shell

pyenv init --install
exec "$SHELL"

This adds the init lines to the shell rc and puts shims first on PATH. For manual setup, use eval "$(pyenv init - bash)" in the interactive rc.

See: pyenv init

Core commands

CommandShows
pyenv versionsInstalled versions
pyenv versionActive version and its origin
pyenv which pythonExecutable behind a shim
pyenv rootInstall directory
pyenv commandsEvery available command

See: Commands reference

Python versions

Available versions

pyenv install --list
pyenv install -l | grep 3.12
pyenv latest --known 3.12

Without --known, pyenv latest only considers installed versions.

See: pyenv latest

Install and uninstall

pyenv install 3.12.16
pyenv install 3.12
pyenv uninstall 3.11.9
pyenv prefix 3.12.16

A partial version installs the latest known patch release. Versions live under $(pyenv root)/versions.

See: pyenv install

Global version

pyenv global 3.12.16
pyenv global system 3.12.16
pyenv global

Writes $(pyenv root)/version; list multiple versions to search them in order.

See: pyenv global

Local version

pyenv local 3.12.16
pyenv local --unset

Writes .python-version in the current directory. Child directories inherit it; parent directories can pin their own.

See: pyenv local

Shell and one-off versions

pyenv shell 3.12.16
pyenv shell --unset
PYENV_VERSION=3.12.16 python
pyenv exec python --version

pyenv shell needs shell integration; PYENV_VERSION works without it. Selection order is shell, local file, parent files, global.

See: pyenv shell

Shims

How shims work

pyenv puts its shims directory first on PATH. Each shim forwards python, pip, and other commands to the selected version; missing commands fall through to system.

See: Understanding shims

Inspect a shim

pyenv which python
pyenv whence pip

which follows the current selection; whence lists every installation that provides the command.

See: pyenv which

Rehash

pyenv rehash
pyenv shims

pyenv reshims on installs and uninstalls. Run pyenv rehash after adding executables outside pyenv.

See: pyenv rehash

Virtual environments

pyenv-virtualenv

git clone https://github.com/pyenv/\
pyenv-virtualenv.git \
  "$(pyenv root)/plugins/pyenv-virtualenv"

Virtualenvs appear as versions under $(pyenv root)/versions.

See: pyenv-virtualenv installation

Create and manage

Create

pyenv virtualenv 3.12.16 myenv
pyenv virtualenv myenv

Manage

pyenv virtualenvs
pyenv uninstall myenv

The one-argument form uses the active version; uninstall removes the environment.

See: pyenv-virtualenv usage

Activate an environment

pyenv activate myenv
pyenv deactivate

Activation needs shell integration: load pyenv init and eval "$(pyenv virtualenv-init -)" in the shell rc. virtualenv-init also follows .python-version when changing directories.

See: Activate virtualenv

Environment per project

pyenv local myenv
pyenv version

pyenv local myenv stores the environment name in .python-version.

See: pyenv-virtualenv

Plain venv

python -m venv .venv
source .venv/bin/activate
deactivate

The stdlib module needs no plugin; pyenv still selects the interpreter version.

See: venv

Plugins

Add plugins

git clone https://github.com/pyenv/pyenv-update.git \
  "$(pyenv root)/plugins/pyenv-update"

Plugins live in $(pyenv root)/plugins; their commands appear in pyenv commands.

See: Plugins wiki

pyenv-update

pyenv update

Updates pyenv and every installed plugin. Homebrew installs use brew upgrade pyenv instead.

See: pyenv-update

Upgrades

Upgrade pyenv

cd "$(pyenv root)" && git pull

For a Git checkout. Use pyenv update above to refresh plugins too.

See: Upgrading pyenv

Upgrade Python

pyenv latest --known 3.12
pyenv install 3.12.16
pyenv global 3.12.16
pyenv uninstall 3.12.15

Install the new patch release, move the version files, then remove the old one.

See: pyenv latest

References

Official resources

Plugins

0 Comments for this cheatsheet. Write yours!