pyenv is a simple yet robust tool for managing multiple Python versions. As a Python developer, you might have faced the situation of needing different Python versions for different projects.
pyenv provides an elegant solution to this problem.
In essence, pyenv is a Python version manager. It allows you to switch between multiple Python versions seamlessly.
It’s a fantastic tool to manage the environment of your Python projects, install Python, switch between Python versions, and much more.
- 1 How pyenv works?
- 2 Installing pyenv on Windows
- 3 Installing pyenv on Linux
- 4 Installing pyenv on MacOS
- 5 Checking pyenv version
- 6 Configuring pyenv environment variables
- 7 Listing all available Python versions
- 8 Installing a specific Python version
- 9 Setting a global Python version (Switch version)
- 10 Setting a local (per-project) Python version
- 11 shell-specific Python version
- 12 Uninstalling a Python version
- 13 What is a virtual environment?
- 14 Creating a virtual environment with pyenv
- 15 Activating and deactivating a virtual environment
- 16 Deleting a virtual environment
- 17 pyenv plugins
- 18 Real-world use cases of pyenv
How pyenv works?
pyenv operates by modifying the
PATH environment variable and using shims to intercept Python commands.
When you run a command like
pip, the operating system uses the directories listed in your
PATH to find the correct executable.
Here’s how it works:
- You run a Python command like
- The operating system searches directories in your
PATHfrom left to right.
- It finds the pyenv shim directory first (since pyenv puts it at the front of your
- The shim passes the command along to pyenv.
- pyenv determines which Python version has been specified by your application.
- It runs your command with the selected version of Python.
This way, you can switch between Python versions on a per-project basis, all thanks to pyenv.
Installing pyenv on Windows
Windows users can use the pyenv-win fork, which is a port of pyenv and is easy to install with the following commands:
# Via pip pip install pyenv-win --target $HOME\.pyenv # Via Homebrew brew install pyenv-win
After running the command, you should close your terminal and open a new one to let the changes take effect.
Note: You need to update your PATH variable to include the Python installation directory if not included.
Installing pyenv on Linux
You can install pyenv on your Linux machine by using the pyenv-installer script from the pyenv repository. Here are the commands to do so:
curl https://pyenv.run | bash
This command downloads and runs the pyenv installer.
Next, you’ll need to add pyenv to your shell so that you can use it directly from your terminal:
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc echo 'eval "$(pyenv init --path)"' >> ~/.bashrc echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
These commands add the necessary lines to your .bashrc file to set up the environment for pyenv.
After running these commands, you should restart your terminal or run the following command to let the changes take effect:
Installing pyenv on MacOS
On MacOS, you can use Homebrew. Here’s how you can install pyenv using Homebrew:
brew update brew install pyenv
After the installation, add pyenv init to your shell to enable shims and autocompletion:
echo 'if command -v pyenv 1>/dev/null 2>&1; then eval "$(pyenv init -)"; fi' >> ~/.bash_profile
Once done, you should restart your terminal for the changes to take effect.
Checking pyenv version
Once you have pyenv installed, you can check its version by running the following command:
This command displays the version of pyenv installed on your system. In this example, the installed pyenv version is 2.3.23.
Configuring pyenv environment variables
pyenv uses several environment variables to control its behavior. One of the most important is
PYENV_ROOT, which defines the location where versions and shims are kept. By default, this is
You can set it like this:
export PYENV_ROOT="$HOME/.pyenv" export PATH="$PYENV_ROOT/bin:$PATH"
These commands set the
PYENV_ROOT variable and add it to your system
To initialize pyenv automatically, you can add the following to your shell profile:
if command -v pyenv 1>/dev/null 2>&1; then eval "$(pyenv init -)" fi
This command checks if pyenv is installed (with
command -v pyenv) and if it is, initializes it (with
eval "$(pyenv init -)").
Listing all available Python versions
pyenv gives you access to a vast range of Python versions. To list all available versions for installation, use the following command:
pyenv install --list
2.1.3 2.2.3 2.3.7 ... 3.8.10 3.9.5 ...
This list is quite long as it includes all Python versions starting from 2.1.3 up to the most recent one.
Installing a specific Python version
To install a specific version of Python, you can use the
pyenv install command followed by the version number.
For instance, to install Python 3.9.5, you can use the following command:
pyenv install 3.9.5
python-build: use email@example.com from homebrew python-build: use readline from homebrew Downloading Python-3.9.5.tar.xz... -> https://www.python.org/ftp/python/3.9.5/Python-3.9.5.tar.xz Installing Python-3.9.5... python-build: use readline from homebrew python-build: use zlib from xcode sdk Installed Python-3.9.5 to /Users/username/.pyenv/versions/3.9.5
This command downloads and installs Python 3.9.5 to the pyenv versions directory.
After the installation, you can use the
pyenv versions command to list all Python versions installed on your system:
* system (set by /Users/username/.pyenv/version) 3.9.5
This output shows that Python 3.9.5 is installed but the system is currently using the global Python version.
Setting a global Python version (Switch version)
With pyenv, you can set a global Python version that will be used in all shells by default. To set a global version, use the
pyenv global command followed by the version number. For instance:
pyenv global 3.9.5
To confirm the global Python version, use the
python --version command:
This output indicates that the global Python version is now set to 3.9.5.
Setting a local (per-project) Python version
pyenv allows you to set a local Python version on a per-project basis.
This version overrides the global Python version within the directory where it’s set. Here’s how you can do it:
First, navigate to your project’s directory:
Then, set the local version for your project:
pyenv local 3.8.10
This command creates a
.python-version file in your current directory with the specified version.
To verify the Python version for the current directory, you can use the
python --version command again:
This shows that Python 3.8.10 is the version for the current directory, regardless of the global Python version.
shell-specific Python version
Shell-specific version is only valid for the current shell session and is not saved to a configuration file. This can be particularly useful if you need to quickly test something in a specific Python version without affecting your global or local versions.
To set a shell-specific Python version, use the
pyenv shell command. For example:
pyenv shell 3.8.10
You can confirm the Python version for the current shell using the
python --version command:
If you close the current terminal and open a new one, the Python version will revert back to the global or local setting.
To clear the shell-specific version within the same session, use the
pyenv shell --unset command:
pyenv shell --unset
Uninstalling a Python version
If you no longer need a specific Python version, you can easily uninstall it using pyenv.
pyenv uninstall command followed by the version number. For example:
pyenv uninstall 3.9.5
You’ll be asked to confirm the operation. After confirming, the specified Python version will be removed from your system.
What is a virtual environment?
A virtual environment is a self-contained directory tree that contains a Python installation for a particular version of Python, plus a number of additional packages.
It’s a way to isolate your Python project and its dependencies from other projects, ensuring that each project has its own set of dependencies that won’t disrupt others.
The use of virtual environments is crucial when you’re dealing with projects that require different versions of packages or Python itself.
By isolating each environment, you can avoid potential conflicts between package versions.
Creating a virtual environment with pyenv
With pyenv, you can create a virtual environment easily. First, ensure that you have the required Python version installed:
pyenv install 3.8.10
Next, create a new virtual environment using the
pyenv virtualenv command:
pyenv virtualenv 3.8.10 my-env
This command creates a new virtual environment named ‘my-env’ with Python 3.8.10.
To list all available virtual environments, you can use the
pyenv virtualenvs command:
3.8.10/envs/my-env (created from /Users/username/.pyenv/versions/3.8.10) my-env (created from /Users/username/.pyenv/versions/3.8.10)
This output shows that you have one virtual environment named ‘my-env’ created with Python 3.8.10.
Activating and deactivating a virtual environment
To activate the virtual environment, you can use the
pyenv activate command:
pyenv activate my-env
Once the virtual environment is activated, the Python version and packages installed in this environment will not affect the rest of the system.
You can confirm the activation by checking the Python version:
This shows that the Python version for the current environment is 3.8.10.
To deactivate the virtual environment and return to the global Python version, use the
pyenv deactivate command:
Deleting a virtual environment
If you no longer need a virtual environment, you can delete it using the
pyenv uninstall command, similar to uninstalling a Python version:
pyenv uninstall my-env
After confirming the operation, the virtual environment ‘my-env’ will be removed from your system.
pyenv supports plugins that extend its functionality. Here are a few useful ones:
pyenv-update: This plugin allows you to update pyenv and all its plugins with a single command.
pyenv-doctor: This plugin checks the health of your pyenv installation and Python builds.
pyenv-which-ext: This plugin adds the
pyenv whichcommand that searches for programs in the directories of the current environment.
You can install these plugins using the same method as installing pyenv, but with the plugin’s Git URL instead of pyenv’s.
Real-world use cases of pyenv
Now that you’ve learned how to use pyenv, let’s discuss its applications in real-world scenarios:
- Testing Across Python Versions: If you’re developing a Python package, you’d likely want to ensure it works across multiple Python versions. pyenv makes it easy to switch between different Python versions for testing.
- Simplified Python Updates: When a new Python version is released, pyenv allows you to install it alongside your existing versions, without affecting your system Python or other projects. You can then test your projects with the new version before fully switching over.
That concludes our tutorial on pyenv. You’re now equipped with a powerful tool for managing multiple Python versions and virtual environments.
Mokhtar is the founder of LikeGeeks.com. He is a seasoned technologist and accomplished author, with expertise in Linux system administration and Python development. Since 2010, Mokhtar has built an impressive career, transitioning from system administration to Python development in 2015. His work spans large corporations to freelance clients around the globe. Alongside his technical work, Mokhtar has authored some insightful books in his field. Known for his innovative solutions, meticulous attention to detail, and high-quality work, Mokhtar continually seeks new challenges within the dynamic field of technology.