PyEnv: Managing Multiple Python Versions With Ease

PyEnv is a tool that allows Python users to switch between multiple versions of Python easily without tampering with the system’s default Python installation. It achieves this by overriding the python command on the command line, which helps you use a specific version for your projects.

Note that PyEnv installs and selects Python interpreters. It doesn’t create isolated environments for your packages. For that, you still use a virtual environment, created with the Python version PyEnv selected.

Which problem does PyEnv solve?

Python, being an evolving language, has multiple versions available for use. At times, developers need to juggle between these versions to ensure compatibility or utilize features from a specific version for a specific project. Managing these versions manually can be challenging and may lead to conflicts or unexpected behaviors.

Another frequent issue developers run into is unexpected Python upgrades. For example, many developers on Macs use Brew. Many brew packages have Python as a dependency. As such, any package upgrade can trigger a change in the Python version installed by Brew. This, in turn, can break a virtual environment since the referenced Python binary is suddenly missing. A similar situation may occur when you use the default Python installation on a Linux machine.

PyEnv solves these issues with:

  1. Per-project versions: Each project can have its own Python version, and PyEnv switches automatically when you enter the project’s directory.
  2. Flexibility: Developers can test their code against multiple Python versions without changing the system settings.
  3. Consistency: Teams can ensure that every member uses the same Python version, leading to a consistent development environment.

How to install PyEnv

It’s important to note that PyEnv works on Unix-like environments, like Linux and Macs. On Windows, see the section on alternatives below. The installation instructions for PyEnv can change occasionally, so it’s best to check the most recent instructions on the PyEnv Github repository. Ensure you follow the steps for your specific shell (bash, zsh, etc.), otherwise the pyenv command won’t work.

Choosing a global Python version with PyEnv

Let’s first set a default, global Python version for your system. This version will be the default when you haven’t set a specific version for a directory or project.

Before we can do so, we need to know the list of available versions:

pyenv install --listCode language: plaintext (plaintext)

This is an extensive list and includes alternative Python interpreters like PyPy. You can also ask for the latest stable version that PyEnv knows about, which you probably want anyway. For example, to see the latest stable Python 3 version:

$ pyenv latest -k 3
3.15.2Code language: plaintext (plaintext)

Without the -k (known) option, pyenv latest shows the latest version you have installed instead. Now we can install the desired version. Python 3.15.2 is the latest version as I write this:

pyenv install 3.15.2Code language: plaintext (plaintext)

PyEnv downloads the source code and compiles Python, so this takes a few minutes. If it fails, you’re probably missing build dependencies; the PyEnv repository has a list per operating system. You can also type just pyenv install 3.15, and PyEnv picks the latest 3.15 release for you.

Once installed, you can set the global version using:

pyenv global 3.15.2Code language: plaintext (plaintext)

Choosing a specific Python version for a project

Now, let’s see how we can use an alternative version for a project. Say we have a project in the folder ~/Code/LegacyProject that requires Python 3.11.

We first need to install this Python version, and we have already learned how to do that:

pyenv install 3.11.18Code language: plaintext (plaintext)

First, navigate to the project’s folder to set the Python version for our legacy project. Then use the command:

pyenv local 3.11.18Code language: plaintext (plaintext)

This sets the Python version for the project and creates the hidden file .python-version file in the directory, ensuring that the specified Python version will be used whenever you’re in this directory.

Suppose you share this legacy project with a colleague who’s also using Pyenv. If this colleague does not have Python 3.11.18 installed yet, Pyenv will notice the file and print a warning like this:

pyenv: version `3.11.18' is not installed (set by ~/Code/LegacyProject/.python-version)Code language: plaintext (plaintext)

Managing Virtual Environments with pyenv-virtualenv

PyEnv can be combined with pyenv-virtualenv, an extension that offers support for managing virtual environments. It allows you to maintain project-specific dependencies without polluting the global namespace. I recommend following the link and seeing if this fits you. Personally, I prefer to keep it simple: PyEnv picks the Python version, and I create a regular venv inside the project with python -m venv .venv. But pyenv-virtualenv certainly has some advantages to note:

  1. Your pyenv-virtualenv will be activated automatically when you enter the directory, which is very convenient. With a regular venv, activating it is an extra manual step.
  2. It allows you to create system-wide virtual environments. For example, you might have a system-wide virtual environment with a particular Python version and particular versions of libraries like NumPy and Pandas.

PyEnv or uv?

These days, uv does the same job and more. It downloads prebuilt Python versions instead of compiling them, so installing one takes seconds, and it doesn’t need shell shims:

$ uv python install 3.15
$ cd ~/Code/LegacyProject
$ uv python pin 3.11
Pinned `.python-version` to `3.11`Code language: plaintext (plaintext)

uv python pin writes the same .python-version file that PyEnv uses, so you can switch between the two tools or use both in one team. The difference is that uv doesn’t replace your python command. Instead, uv uses the pinned version when you run uv run or create a virtual environment with uv venv. uv also manages virtual environments and dependencies, so for new projects it covers everything PyEnv and pyenv-virtualenv do.

PyEnv is still a good choice if you want a plain python command that switches versions per directory, or if you need an unusual build, like a debug build.

On Windows, PyEnv itself doesn’t work. Since Python 3.14, the official way to manage several Python versions on Windows is the Python install manager: py install 3.11 installs a version, py list shows what you have, and py -V:3.11 runs a specific one. See the official documentation for details. uv works on Windows too.

Conclusion

PyEnv is an invaluable tool for Python developers aiming to maintain consistency and flexibility across projects. Whether you’re developing across different versions of Python or trying to maintain a consistent environment among a team, PyEnv offers a seamless and efficient solution.

Related articles

Leave a Comment