pyenv is a tool that enables the use of multiple python versions onto a single computer, meaning we can use a different python version for each project. In addition to python versions, pyenv also manages the installation of project-specific packages and python modules, so that each python project can benefit from both its own python version and undisturbed coding environment.

pyenv's base functionality (plugin-less) allows to install and manage different python versions on a single computer, in addition to the base python (the python version used by the OS if there is one). Once pyenv is installed on your machine, which should be the case through the installator, you'll find a hidden .pyenv directory in your home directory /Users/username/.pyenv/ that stores all those versions in the versions subdirectory, respectively C:\Users\username\.pyenv and pyenv-win\versions under Windows.

The few useful commands part of pyenv are as follows:

pyenv install -l # displays all installable python versions
pyenv install 3.11.0 # installs python 3.11.0 on your local machine, ready to be used
pyenv install 3.10.5 # installs python 3.10.5 on your local machine, ready to be used
pyenv global 3.11.0 # Sets the 3.11.0 python version as the global python version, i.e. used by the python command when no local rule is set
pyenv local 3.10.5 # Sets the 3.10.5 python version as the local python version (local to the folder and subfolders), overriding the global rule
pyenv versions # lists all available python versions installed through and managed by pyenv

With python versions now installed, the pyenv-virtualenv plugin of pyenv enables the setting up of virtual environments within those python versions meant to host all python-related packages. This means that once a virtual environment is activated, installing packages through pip will install packages only locally to that environment, hence not possibily overwriting package versions for other projects.

This plugin is already installed on your machine through the installer but ONLY for MacOS and Linux. For Windows there is an equivalent (pyenv-win-venv) but the usage commands differ quite a bit and this brings only the advantage of saving disk space. Then under Windows the virtual environment can be "simulated" by duplication. It take more disk space but the end user result is the same. Then use the command pyenv duplicate python_version env_name for Windows instead pyenv virtualenv python_version env_name for MacOS/Linux.

The few useful commands part of pyenv-virtualenv are as follows:

pyenv virtualenv 3.11.0 myenv # Creates a virtualenv called myenv using python version 3.11.0

pyenv duplicate 3.11.0 myenv # Creates a virtualenv called myenv using python version 3.11.0

pyenv local myenv # Links the myenv environment to the current folder and subfolders
pyenv versions    # List all python versions and virtual or duplicated environments
pyenv             # Display the pyenv version and a more useful pyenv commands (differ for Windows)

If you're encountering issues with the pyennv installation on your machine, please check if your issue is explained on this page, else contact us directly by email.