Simple Python Version Management: pyenv


pyenv lets you easily switch between multiple versions of Python. It's
simple, unobtrusive, and follows the UNIX tradition of single-purpose
tools that do one thing well.

This project was forked from rbenv and
ruby-build, and modified for Python.

What pyenv _does..._

• Lets you change the global Python version on a per-user basis.
• Provides support for per-project Python versions.
• Allows you to override the Python version with an environment

• Searches for commands from multiple versions of Python at a time.

In contrast with pythonbrew and pythonz, pyenv _does not..._

• Depend on Python itself. pyenv was made from pure shell scripts.

• Need to be loaded into your shell. Instead, pyenv's shim

• Manage virtualenv. Of course, you can create virtualenv

----

Table of Contents

• [Installation](#installation)

• [Usage](#usage)

• [Upgrading](#upgrading)

• [Uninstalling pyenv](#uninstalling-pyenv)
• [Pyenv plugins](#pyenv-plugins)
• [How It Works](#how-it-works)

• [Advanced Configuration](#advanced-configuration)

• [Development](#development)

----

Installation

A. Getting Pyenv

Linux/Unix

The Homebrew option from the [MacOS section below](#macos) would also work if you have Homebrew installed.

1. Automatic installer (Recommended)

bash
curl -fsSL https://pyenv.run | bash

For more details visit our other project:
https://github.com/pyenv/pyenv-installer

2. Basic GitHub Checkout

This will get you going with the latest version of Pyenv and make it
easy to fork and contribute any changes back upstream.

• Check out Pyenv where you want it installed.

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

• Optionally, try to compile a dynamic Bash extension to speed up Pyenv. Don't

cd ~/.pyenv && src/configure && make -C src

MacOS

The options from the [Linux section above](#linuxunix) also work but Homebrew is recommended for basic usage.

Homebrew in macOS

sh
      brew update
      brew install pyenv

sh
      brew install pyenv --head

4. OPTIONAL. To fix brew doctor's warning _""config" scripts exist outside your system or Homebrew directories"_

If you're going to build Homebrew formulae from source that link against Python
like Tkinter or NumPy
_(This is only generally the case if you are a developer of such a formula,
or if you have an EOL version of MacOS for which prebuilt bottles are no longer provided
and you are using such a formula)._

To avoid them accidentally linking against a Pyenv-provided Python,
add the following line into your interactive shell's configuration:

* Bash/Zsh:

~~~bash
alias brew='env PATH="${PATH//$(pyenv root)\/shims:/}" brew'
~~~

* Fish:

~~~fish
alias brew="env PATH=(string replace (pyenv root)/shims '' \"\$PATH\") brew"
~~~

Windows

Pyenv does not officially support Windows and does not work in Windows outside
the Windows Subsystem for Linux.
Moreover, even there, the Pythons it installs are not native Windows versions
but rather Linux versions running in a virtual machine --
so you won't get Windows-specific functionality.

If you're in Windows, we recommend using @kirankotari's pyenv-win fork --
which does install native Windows Python versions.

B. Set up your shell environment for Pyenv

The below setup should work for the vast majority of users for common use cases.
See [Advanced configuration](#advanced-configuration)
and specifically [Manual shell setup](#manual-shell-setup) for details and more configuration options.

To add the suggested setup code to the startup files of the running shell,
run --install.
Specifically:

• If you installed Pyenv with the installer script:

sh
~/.pyenv/bin/pyenv init --install

• If you installed Pyenv with Homebrew:

sh
pyenv init --install

For Bash, avoid the automatic --install path if your BASH_ENV points to
.bashrc; use the manual Bash instructions below so the eval "$(pyenv init - bash)"
line only goes in your login startup file.

C. Restart your shell

for the PATH changes to take effect.

sh
  exec "$SHELL"

D. Install Python build dependencies

Install Python build dependencies
before attempting to install a new Python version.

You can now begin using Pyenv.

E. Upgrade Notes

if you have upgraded from pyenv version 2.0.x-2.2.x

The startup logic and instructions have been updated for simplicity in 2.3.0.
The previous, more complicated configuration scheme for 2.0.0-2.2.5 still works.

• Define environment variable PYENV_ROOT to point to the path where

• Add the pyenv executable to your PATH if it's not already there
• run eval "$(pyenv init -)" to install pyenv into your shell as a shell function, enable shims and autocompletion

----

Usage


Install additional Python versions

To install additional Python versions, use [pyenv install](COMMANDS.md#pyenv-install).

For example, to download and install Python 3.10.4, run:

sh
pyenv install 3.10.4

Running pyenv install -l gives the list of all available versions.

----

Notes about python releases

NOTE: Most Pyenv-provided Python releases are source releases and are built
from source as part of installation (that's why you need Python build dependencies preinstalled).
You can pass options to Python's configure and compiler flags to customize the build,
see [_Special environment variables_ in Python-Build's README](plugins/python-build/README.md#special-environment-variables)
for details.

NOTE: If you are having trouble installing a Python version,
please visit the wiki page about
Common Build Problems.

NOTE: If you want to use proxy for download, please set the http_proxy and https_proxy
environment variables.

NOTE: If you'd like a faster interpreter at the cost of longer build times,
see [_Building for maximum performance_ in Python-Build's README](plugins/python-build/README.md#building-for-maximum-performance).

----

Prefix auto-resolution to the latest version

All Pyenv subcommands except uninstall automatically resolve full prefixes to the latest version in the corresponding version line.

pyenv install picks the latest known version, while other subcommands pick the latest installed version.

E.g. to install and then switch to the latest 3.10 release:

sh
pyenv install 3.10
pyenv global 3.10

You can run [pyenv latest -k ](COMMANDS.md#pyenv-latest) to see how pyenv install would resolve a specific prefix, or [pyenv latest ](COMMANDS.md#pyenv-latest) to see how other subcommands would resolve it.

See the [pyenv latest documentation](COMMANDS.md#pyenv-latest) for details.

----

Python versions with extended support

For the following Python releases, Pyenv applies user-provided patches that add support for some newer environments.
Though we don't actively maintain those patches, since existing releases never change,
it's safe to assume that they will continue working until there are further incompatible changes
in a later version of those environments.

• *3.7.8-3.7.15, 3.8.4-3.8.12, 3.9.0-3.9.7* : XCode 13.3
• *3.5.10, 3.6.15* : MacOS 11+ and XCode 13.3
• *2.7.18* : MacOS 10.15+ and Apple Silicon

----

Switch between Python versions

To select a Pyenv-installed Python as the version to use, run one
of the following commands:

• [pyenv shell ](COMMANDS.md#pyenv-shell) -- select just for current shell session
• [pyenv local ](COMMANDS.md#pyenv-local) -- automatically select whenever you are in the current directory (or its subdirectories)
• [pyenv global ](COMMANDS.md#pyenv-global) -- select globally for your user account

~~~bash
pyenv global 3.10.4
~~~

Now whenever you invoke python, pip etc., an executable from the Pyenv-provided
3.10.4 installation will be run instead of the system Python.

Using "system" as a version name would reset the selection to your system-provided Python.

See [Understanding shims](#understanding-shims) and
[Understanding Python version selection](#understanding-python-version-selection)
for more details on how the selection works and more information on its usage.

----

Making multiple versions available

You can select multiple Python versions at the same time by specifying multiple arguments.
E.g. if you wish to use the latest installed CPython 3.11 and 3.12:

~~~bash
pyenv global 3.11 3.12
~~~

Whenever you run a command provided by a Python installation, these versions will be searched for it in the specified order.
[Due to the shims' fall-through behavior]((#understanding-python-version-selection)), system is always implicitly searched afterwards.

----

Uninstall Python versions

As time goes on, you will accumulate Python versions in your
$(pyenv root)/versions directory.

To remove old Python versions, use [pyenv uninstall ](COMMANDS.md#pyenv-uninstall).

Alternatively, you can simply rm -rf the directory of the version you want
to remove. You can find the directory of a particular Python version
with the pyenv prefix command, e.g. pyenv prefix 2.6.8.
Note however that plugins may run additional operations on uninstall
which you would need to do by hand as well. E.g. Pyenv-Virtualenv also
removes any virtual environments linked to the version being uninstalled.

----

Other operations

Run pyenv commands to get a list of all available subcommands.
Run a subcommand with --help to get help on it, or see the [Commands Reference](COMMANDS.md).

Note that Pyenv plugins that you install may add their own subcommands.

Upgrading

Upgrading with Homebrew

sh
brew upgrade pyenv

To switch from a release to the latest development head of Pyenv, use:

sh
brew uninstall pyenv
brew install pyenv --head

then you can upgrade it with brew upgrade pyenv as usual.

Upgrading with Installer or Git checkout

If you've installed Pyenv with Pyenv-installer, you likely have the
Pyenv-Update plugin that would
upgrade Pyenv and all installed plugins:

sh
pyenv update

If you've installed Pyenv using Pyenv-installer or Git checkout, you can also
upgrade your installation at any time using Git.

To upgrade to the latest development version of pyenv, use git pull:

sh
cd $(pyenv root)
git pull

To upgrade to a specific release of Pyenv, check out the corresponding tag:

sh
cd $(pyenv root)
git fetch
git tag
git checkout v0.1.0

Uninstalling pyenv

The simplicity of pyenv makes it easy to temporarily disable it, or
uninstall from the system.

1. To disable Pyenv managing your Python versions, simply remove the
pyenv init invocations from your shell startup configuration. This will
remove Pyenv shims directory from PATH, and future invocations like
python will execute the system Python version, as it was before Pyenv.

pyenv will still be accessible on the command line, but your Python
apps won't be affected by version switching.

2. To completely uninstall Pyenv, remove _all_ Pyenv configuration lines
from your shell startup configuration, and then remove
its root directory. This will delete all Python versions that were
installed under the ` $(pyenv root)/versions/ directory:

sh
    rm -rf $(pyenv root)

brew uninstall pyenv

The main idea is that most things that you can put under $PYENV_ROOT/` you can also put
un

…

Collapse