Python virtual environment

Photo by Stephen Pedersen on Unsplash

Photo by Stephen Pedersen on Unsplash

Python programming, just like any other programming is heavily dependent on external libraries/modules. With PIP, it's easy to install dependencies from PyPI.

What do you do when you have to work on two or more projects that require different versions of the same module, and where the newest version introduces breaking changes? The solution is to use the Python virtual environment module called venv.

In this article, I will explain how venv works, how you can use it on your own projects, and on projects you clone from repos like GitHub.

How it works

Virtualization with Python

Python venv works at a high level in a similar way like Linux chroot, and containerization works. It creates a virtual wall around a directory that prevents Python from accessing system-installed modules.

By using venv you install every dependency with PIP, and those modules will be installed in the project directory only. When you run the files within that directory it can only access modules installed in that project directory.

By using venv, you can completely separate dependencies for each project much like you can with NPM for JavaScript projects, and Composer for PHP projects.

Create and activate

On your host, you create a new virtual environment directory by first navigating into your project directory and running this command

python -m venv venv

This will create a "venv" directory in your project where your virtual environment files will be stored.

To activate the virtual environment for the project you will have to run separate script depending on what OS your are running. For Windows hosts, use this command:


On Linux, and Mac you run this commands:

chmod +x venv/bin/activate # make the script executeable
source venv/bin/activate

Please note that the virtual environment is Python version specific. If you need to run a non-default version of Python on your system, you must specify what Python version you want to use the venv with. If the virtual environment is created for Python 3.8, it will not work with Python 3.11, and vice versa.

To do so you must prefix the pip commands with "python3.11" or the version you are using. This applies to every pip command demonstrated in this article.

Every Python module you install with PIP will be saved inside the venv directory for that project when venv is activated. They will not conflict with system-installed modules or modules installed on other projects' venv.


When you no longer need the virtual environment for a project it can be deactivated simply be running the deactivate command in your terminal.


Once the venv is deactivated the project can access system-installed Python modules.


It's best practice to not keep a version control of installed project dependency files. Because of this, you should add the venv directory to your .gitignore file on git-based projects.

vim .gitignore

The venv directory will not be tracked by git when it's added to the .gitignore file.

Saving dependencies

To make it easy for yourself and others to install every dependency needed by the project you can use a PIP tool called freeze. This outputs installed modules, and what version of those modules are installed to the venv.

It's best practice to store those dependencies as a file called requirements.txt

To save or update the requirements.txt file, simply run this command.

pip freeze > requirements.txt

This file will be used to install dependencies and should be committed to your project's git.

Install dependencies

To install dependencies defined in a requirements.txt file you use the file as a parameter to PIP install.

pip install -r requriements.txt

Uninstall dependencies

When you no longer need a dependency for a project you simply uninstall it with PIP, and update the requirements.txt file.

pip uninstall pygame
pip freeze > requirements.txt