Python Virtual Environments and Requirements Files

What is a Python Virtual Environment?

It is a directory on your computer you set up so you can install and use specific versions of Python packages for a project.

Why use it?

This is useful in several situations.

Say you were working on two projects. One required NumPy 1.9 and another required NumPy 2.0. If you had to use the system’s installed version of NumPy, then you would have to uninstall the current version and install the other version every time you wanted to switch the project you were working on.

Or, if you are considering upgrading to a new major version of a package and you want to test it out before you upgrade your system’s version, creating a virtual environment would allow you to try it before installing it before upgrading the version.

It’s also just really nice to have everything your project needs in a single directory where you know what all the package dependencies are.

Creating, Activating, and Leaving Python Virtual Environments

Creating a virtual environment named “.venv” is as simple as:

python3 -m venv .venv

Once it is created, you can get into the virtual environment by activating it.

On Linux/Mac, the command for activating a virtual environment named “.venv” is:

source .venv/bin/activate

On Windows, the command is:

.venv\Scripts\activate

Exiting the virtual environment is as simple as:

deactivate

Installing and Working with Packages Manually

When you are in the virtual environment, you can run the following to see what you have installed in the environment:

pip list

Being on an old version of pip can cause problems so it is generally a good idea to upgrade pip to the latest, which can be done with the following command.

pip install --upgrade pip

Installing a package in your virtual environment is as simple as running pip install. For instance, if we wanted to install numpy, we would run:

pip install numpy

Here is an example of what you can expect to see from a fresh virtual environment with numpy installed:

(.venv) brent % pip list
Package    Version
---------- -------
numpy      2.0.1
pip        24.2
setuptools 49.2.1

And if you run python, you should be able to import numpy:

(.venv) brent % python
Python 3.9.1 (default, Jul 13 2024, 10:31:12) 
[Clang 13.0.0 (clang-1300.0.29.3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import numpy
>>>

Working with Requirements Files

A requirements.txt is a file that lists the packages of an environment. This file can be used to install the listed packages. It is useful for sharing the environment you are working in with other developers.

Saving a Requirements File

Let’s say we wanted to share a project we were working on in a virtual environment where we have numpy and pandas. When you are in your virtual environment, you can use pip freeze like below to save a requirements.txt:

pip freeze > requirements.txt

The requirements.txt would look like this:

numpy==2.0.1
pandas==2.2.2
python-dateutil==2.9.0.post0
pytz==2024.1
six==1.16.0
tzdata==2024.1

Installing Packages From a Requirements File

When you have a requirements.txt, you can use that to set up a virtual environment for a project. Just copy the requirements.txt to the directory you want to create the virtual environment in, activate the virtual environment, and run the following command:

pip install -r requirements.txt

And that is all you need to get started with Python virtual environments and requirements files. Happy coding!