As Python developers we often need to work with multiple versions of Python.
pyenv lets us easily install, manage
and switch between multiple versions of Python.
In this post I will provide an overview of the installation and usage of
pyenv. The installation instructions are
for Mac OS X and Homebrew. If you are not on Mac OS X or don't use Homebrew, refer to the
documentation for installation instructions specific to your system.
The rest of the post is about the usage of
pyenv and is applicable to everyone.
Python versions installed using
pyenv can coexist with other Pythons installed via Homebrew or the system Python.
If you have already installed Python using Homebrew, you don't need to uninstall it.
See the How pyenv Works? section below to understand how all the different Python versions
coexist on the same system.
pyenv on Mac OS X is very simple with Homebrew.
$ brew update $ brew install pyenv
After installation, add the following at the bottom of your profile (
if which pyenv > /dev/null; then eval "$(pyenv init -)"; fi
~/.pyenv as its root directory by default. This is the directory where
pyenv installs its
shims, the different Python versions and its plugins. The default location is absolutely
fine, but if you want to use the directory suggested by Homebrew then add the following to your profile.
Finally, restart your shell so the profile changes can take effect.
pyenv provides various commands to manage the different Python versions.
Installing new Python versions is very straightforward. All Python versions are installed in the
versions directory under the
$ pyenv install 2.7.10 $ pyenv install 3.4.3 $ pyenv install 3.5.0
If you no longer need a Python version installed using
pyenv, you can easily uninstall it.
$ pyenv uninstall 3.5.0
Lists all the currently installed Python versions. The asterisk indicates the currently active version. The
version is the one that already existed in your system and was not installed by
$ pyenv versions * system (set by /Users/akbar/.pyenv/version) 2.7.10 3.4.3
Displays the currently active Python version.
$ pyenv version system (set by /Users/akbar/.pyenv/version)
Sets the global version of Python to be used in all shells. This command writes the specified version number to the
version file under the
$ pyenv global 2.7.10
When run without a version number, it displays the currently configured global version.
Sets the Python version to be used by a specific application. This command writes the specified version number to the
.python-version file in the in the current directory. This version overrides the global version and is used for the
current directory and all its sub-directories.
$ pyenv local system
You can also unset the local version with the following command. This deletes the
.python-version file from the current
$ pyenv local --unset
When run without a version number, it displays the currently configured local version.
$ pyenv local
Sets a version of Python for the current shell session. This command sets the
PYENV_VERSION environment variable in
your shell to the specified version. This setting overrides the local and global versions of Python.
$ pyenv shell 3.4.3
You can reset the Python to a different version by executing this command again with the required version.
$ pyenv shell 2.7.10
You can also unset the shell version with the following command.
$ pyenv shell --unset
When run without a version number, it displays the current version configured for the shell.
$ pyenv shell 2.7.10
Displays the full path of the executable which will be invoked when a command is run.
$ pyenv which pydoc /Users/akbar/.pyenv/versions/2.7.10/bin/pydoc
Lists all Python versions that have the given command installed.
$ pyenv whence pydoc 2.7.10 3.4.3
How pyenv Works?
The fundamental concept behind
pyenv is a shim.
A shim is a small library or program that transparently intercepts calls and changes the arguments passed, handles the operation itself or redirects the operation elsewhere.
pyenv creates a directory of shim commands that have the same names as all the executables (such as
pip) distributed with all the installed Python versions. The directory of shims is kept up to date
every time a new Python version or a new library is installed.
The directory of shims is then inserted at the front of your
PATH. So when you run a command, say
- The shell searches your
PATHfor an executable file matching the command name.
- Since the shim directory is at the front of the
PATH, the shim executable with the same name as the command is matched first.
- The shell then runs the shim executable, which passes the command to
pyenvchooses the correct Python version and then executes the command in that Python version.
How pyenv choses a Python version?
pyenv uses the first Python version found by looking at the following sources in the specified order.
- The shell Python specified by the
- The local Python specified by the
.python-versionfile in the current directory or the parent directories of the current directory.
- The global Python specified by the
versionfile under the
- The system Python.