Python Environment Management for Everyone - The Easy Way

Python and its package management is pure pain.

I have the feeling there are more tools around package management than libraries on PyPi.

I would recommend this to everybody using Python in multiple projects and possibly even different Python versions. I did not come up with this, but it is the dumbed down version of this amazing article I have bookmarked for ages:

Managing Multiple Python Versions With pyenv – Real Python

In this step-by-step tutorial, you’ll learn how to install multiple Python versions and switch between them with ease, including project-specific virtual environments, even if you don’t have sudo access with pyenv.

Real PythonLogan Jones

If you want to have a deep dive, go ahead and read that article. It is pure gold 👌

Anyway, here is the short version.

Do not use Python from your OS

It does not matter what you run, do not use your operating system Python version.

If you install package A to that Python version and you need a different version of package A in a different project, you are already in version hell. You can solve this, with virtualenv but what if you need a different Python version as well (like 3.11.0 vs 3.12.0)? Virtualenv does not help you with that AFAIK.

The easy solution: pyenv

If you are not allowed to use your system Python, then which one should you use? You can install and manage multiple Python versions very easily with pyenv.

So install pyenv checking their GitHub. This is mostly for Linux and Mac, but I believe there is a fork for Windows mentioned as well:

GitHub - pyenv/pyenv: Simple Python version management

Simple Python version management. Contribute to pyenv/pyenv development by creating an account on GitHub.

GitHubpyenv

When you have pyenv installed, you can list what is available. They even offer different Python "distributions" like Anaconda which already has a lot of packages preinstalled for data science stuff. But also niche things like PyPy that you could put on systems that do not have a package manager and still get a full Python runtime.

Pick your poison from this list (truncated output):

pyenv install --list

Available versions:
  [...]
  3.12.9
  3.13.0
  3.13.0t
  3.13-dev
  3.13t-dev
  3.13.1
  3.13.1t
  3.13.2
  3.13.2t
  3.14.0a5
  3.14.0a5t
  3.14-dev
  3.14t-dev
  [...]
  anaconda-1.4.0

Install your Python version:

pyenv install 3.11.9

Now, you create a new virtual environment for your project. Let's say, I want to use 3.11.9 for my PokyPow project:

pyenv virtualenv 3.11.9 pokypow

You can actually name your virtual environments anything you want. Sometimes I use project-python-version like: pokypow-3.11.9.

Now you can activate your virtualenv with this:

pyenv activate pokypow

Most shells will show you that you are now working in that specific virtualenv. In my case Oh-My-ZSH:

Automate Python environment switching

Now you can activate your Python pyenv virtualenv, install packages via pip, switch to another project, and do the same.

But we are not cavemen!

You can create a .python-version file in your project. This will automatically switch the Python version when you change the directory and that is super handy!

The file just contains a single line entry with the virtualenv name:

cat .python-version
pokypow

Here a one-liner to create it in your current directory:

echo "pokypow" > .python-version

Happy hacking!