It's common for developers to work on multiple Python projects, which often results in the need for different Python versions on our systems. Without good tooling, it can become painful to switch betweeb Python versions and virtual environments. That's where pyenv and pyenv-virtualenv come in. These lightweight tools make it easy to switch between Python versions when working on multiple projects, ensuring that each project has its own isolated virtual environment.
This post looks at what these tools are, when to use then and a few basic commands to help you get started.
What pyenv Does
Pyenv lets you install and manage multiple versions of Python on the same machine. This is useful when you work on different projects which require different versions of Python, especially if you don't want to depend on your built-in system Python. Additionally, you can set things up so that per-project Python versions automatically activate when you enter a folder.
You can also use pyenv to set your global system Python version.
What pyenv-virtualenv does
Pyenv handles Python versions, pyenv-virtualenv handles virtual environments. Python virtual environments keep dependencies isolated from your global system Python installation, and from other projects.
With pyenv-virtualenv, you can create virtual environments using specific Python versions and automatically activate these virtual environments when entering project folders.
Pyenv and pyenv-virtualenv are great if you're working on different projects where some are pinned to older or specific Python releases.
Installation
Installing these tools is pretty simple. The basics are below, but check out the documentation for specific instructions.
macOS: Install via Homebrew:
brew install pyenv pyenv-virtualenv
Linux/WSL
curl -fsSL https://pyenv.run | bash
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
exec "$SHELL"
The commands above might also output some init lines that you can add to your shell configuration (like .bashrc or .zshrc).
Once this is done, you're ready to install Python versions and create virtual environments.
Basic Commands
Managing Python Versions
pyenv install --list # See available versions that can be installed
pyenv install 3.14.0 # Install a specific version
pyenv global 3.14.0 # Set the global system python version
pyenv local 3.14.0 # Set a version for the current folder ( using .python-version)
Creating and Using Virtual environments
pyenv virtualenv 3.14.0 my-project-env # Create a venv
pyenv activate my-project-env # Activate a venv
pyenv deactivate # Deactivate a venv
To auto-activate a virtual environment when entering a project directory:
echo "my-project-env" > .python-version
Cleaning up
It's always good to remove old, unused versions and environments.
pyenv uninstall 3.10.0
pyenv virtualenv-delete my-old-env
Managing Multiple Projects
When you're working on multiple projects, this common workflow should be useful.
- Create a new folder
- Install or choose a Python version for your new folder
- Create a virtual environment
- Link the environment to the project using
.python-version
Example:
mkdir my-project
cd my-project
pyenv install 3.14.0 # If your version is not installed yet
pyenv virtualenv 3.14.0 my-project-env
echo "my-project-env" > .python-version
Any pip install calls will stay inside the my-project-env environment from here.
Alternatives
If pyenv doesn't work for your needs, there are some other options:
python -m venvis lightweight and included with Python.- Poetry manages dependencies and environments in a single tooling
- Conda is great for data science stacks
- Docker works very well for fully isolated, repeatable environments.
No single tool will work for everyone; it depends on how you like to stricture your development workflow. Personally, I like pyenv and pyenv-virtualenv for the simplicty and flexibility they provide.
Final Thoughts
Pyenv and pyenv-virtualenv offer an easy, flexible method for managing Python versions and virtual environments while staying out of your way. If you're working on multiple Python projects and need clean isolation between environments, these tools are a great fit.