Getting started
Introduction
pyenv installs Python versions, selects them per project, and exposes their commands through shims.
- pyenv documentation (github.com)
- Commands reference (github.com)
- Common build problems (github.com)
- pyenv-virtualenv (github.com)
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.
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
| Command | Shows |
|---|---|
pyenv versions | Installed versions |
pyenv version | Active version and its origin |
pyenv which python | Executable behind a shim |
pyenv root | Install directory |
pyenv commands | Every 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.
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.
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
- pyenv repository (github.com)
- Commands reference (github.com)
- pyenv wiki (github.com)
Plugins
- pyenv-virtualenv (github.com)
- pyenv-update (github.com)
- Plugins wiki (github.com)
0 Comments for this cheatsheet. Write yours!