- Blog posts/
Virtual Environment with pyenv
Table of Contents
Python is a popular programming language and often times we need to import external libraries to help us perform various tasks. However, Python and those external libraries have many different versions, sometimes one python version may not support the libraries that we need, or some of our projects just require a different version of external libraries than another one. When we only have one python installation in our computer and have only that one place to install our packages, we cannot perform all the tasks that have different version requirements for Python or the packages.
One way to handle this is to create a virtual environment, where the Python (interpreter), libraries and scripts installed into it can be isolated from those installed in other virtual environments.
pyenv can help us install different versions of python and easily switch between them;
pyenv-virtualenv is a pyenv plugin that provides features to manage virtualenvs (and conda environments) for Python on UNIX-like systems.
Note there are other ways to create virtual environments, this is just one way.
Step 1: Install pyenv and pyenv-virtualenv #
For MacOS users, you can install
Homebrew. If you do not have Homebrew on your computer yet, run the following command in your terminal to install Homebrew first (check
for more information).
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
After that, install
pyenv by running the following commands in your terminal:
brew update brew install pyenv
pyenv-virtualenv by running either of the the following 2 commands:
brew install pyenv-virtualenv brew install --HEAD pyenv-virtualenv # install the latest development version
Step 2: Set up shell environment for Pyenv #
Depends on your shell type, you need set up the shell environment differently. To check what shell type you have on your computer, open your terminal and it will show up on the top part of the terminal window. The following setup should work for the majority of users for common use cases(see below).
- For Zsh
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc echo 'eval "$(pyenv init -)"' >> ~/.zshrc
- For bash:
# add the commands to ~/.bashrc echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc echo 'eval "$(pyenv init -)"' >> ~/.bashrc # add the commands to ~/.profile echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile echo 'eval "$(pyenv init -)"' >> ~/.profile # add the commands to ~/.bash_profile echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile echo 'eval "$(pyenv init -)"' >> ~/.bash_profile
In order to make
pyenv-virtualenv work, you need to further add the following:
eval "$(pyenv virtualenv-init -)"
After the shell setup steps, remember to restart the shell for the changes to take effect by running
Step 3: Use pyenv and pyenv-virtualenv #
1. pyenv usage #
Before installing any new python version with
pyenv, first install Python build dependencies following the instructions
Suggested build environment session.
By simply typing
pyenv in the terminal, you will get a preview of some useful pyenv commands there. The following are some common commands.
Install/uninstall additional python version
pyenv install <version> # install e.g. pyenv install 3.7.14 pyenv uninstall <version> # uninstall
You can check all the available versions by running the following command:
pyenv install --list | grep " 3\." # This will list all the available python versions of 3.6 above
Check Python versions installed under pyenv
the one with the * in front is the global/default python version. Note that if you have conda installed, the python version under conda environment will not show here.
Switch versions/deactivate pyenv
pyenv shell <version> # select version for current shell session pyenv local <version> # Set default version for the current directory (or its subdirectories) pyenv global <version> # set global version for user account pyenv shell --unset # deactivate pyenv
2. pyenv-virtualenv usage #
Create a virtual environment with specific python version
pyenv virtualenv <python_version> <venv_example> # e.g. pyenv virtualenv 3.10.4 venv_test
Install packages in the created virual environment
pyenv local <venv_example> # first go to the virtual environment pip install <package> # install packages using pip install
Use the virtual environment
There are multiple ways to use the virtual environment.
If you want to automatically activate the virtual environment for a project folder, you can either
- create a
.python-versionfile in the project folder by running the following command in the terminal:
echo <venv_example> > <project_folder_path>/.python-version # e.g. echo venv_test > '/Users/yanhe/Desktop/test-env'/.python-version
- go to the project from a terminal, and run:
pyenv local <venv_example>
Then everytime you enter the project folder, the virtual environment will be automatically activated, and your codes under that project folder will automatically run via the virtual environment.
- create a
If you want to (permanently) change the (default) virtual environment for the project folder, you can achieve that by running:
pyenv local <new_venv>
- if you use the virual environment by creating the
.python-versionfile, you will notice that the
.python-versionfile also changes automatically whenever you change the default virtual environment, it always corresponds to the name of the virtual environment that you set.
- You need to re-enter the project folder everytime after you run
pyenv local <venv>in order to make the new virtual environment take effect.
You can always check the (default/permenant) virtual environment for your project folder by opening a terminal under that folder and running:
- if you use the virual environment by creating the
If you are working in VS Code you can activate a virtual environment by pressing
Python: Select Interpreter, refresh by clicking the refreshing bar on the top right (this should give you all available choices in your computer) and choose the virtual environment that you want, this will not change the default virtual environment.
If you want to temporarily switch to a different virtual environment in current terminal, you can open a terminal and run the following command:
pyenv shell <new_venv>
Collaborating with others #
The best part about working with virtual environments is how easy it becomes to work with others on projects. All you need to do is let them know what python version your using and give them a snapshot of your environment using
pip freeze > requriements.txt. Now they are able to recreate your environment on their laptop without changing their global settings.
It is good practice to have a base environment as your starting shell and then create a new environment for each project you work on.
Have fun with your Python virtual environments :)
Some other useful links: