Python Virtual Environments

Summary: in this tutorial, you’ll learn about Python virtual environments and how to use the venv module to create a virtual environment.

Why do you need Python virtual environments #

Python stores all system packages in a specified folder when installing Python. Typically, most system packages locate at subfolders of a path specified in the sys.prefix. To find this path, you can import the sys module and display it as follows:

import sys

print(sys.prefix)Copy

It’ll show something like this on Windows:

C:pythonCopy

When you use pip to install third-party packages, Python stores these packages in a different folder specified by the site.getsitepackges() function:

import site
print(site.getsitepackages())Copy

It returns something like this on Windows:

['C:\python', 'C:\python\Lib\site-packages']Copy

You’ll be fine if you have some projects that use only standard Python libraries. However, it’ll be a problem when you have some projects that use third-party packages.

Suppose you have two projects that use different versions of a library. Since there is only one location to store the third-party packages, you cannot keep different versions at the same time.

A workaround is that you can use the pip command to switch between versions by installing/uninstalling the packages. However, it will be time-consuming and not scale very well.

This is where virtual environments come into play.

What is a Python virtual environment #

Python uses virtual environments to create an isolated environment for every project. In other words, each project will have its own directory to store third-party packages.

In case you have multiple projects that use different versions of a package, you can store them in separate virtual environments.

Python includes the virtual environment module (venv) as a standard library since version 3.3. Therefore, to use the venv module, you should have Python 3.3 or later.

To check the Python’s version, you can use the following command:

python --versionCopy

Using the venv module to create a virtual environment #

The following example shows you how to create a new project on Windows, which uses a virtual environment created by the venv built-in module.

First, create a new folder for hosting the project and virtual environment:

mkdir D:test_env
cd test_envCopy

Second, create a virtual environment with the name .venv inside the test_env folder:

python -m venv .venvCopy

The above command will create a new folder called .venv with all necessary tools and libraries for running Python programs.

Second, activate the virtual environment by running the activate.bat file in the project_env/Scripts directory:

.venvScriptsactivateCopy

Once executed, you’ll see the following in the terminal:

(.venv) D:test_env>Copy

The prefix (.venv) indicates that you’re in the .venv virtual environment.

Now, you can check where the python.exe is located:

where pythonCopy

This time it returns the following paths:

D:test_env.venvScriptspython.exe
C:pythonpython.exe
C:Users<username>AppDataLocalMicrosoftWindowsAppspython.exeCopy

The first line shows that the python.exe is located in the .venv/Scripts folder. It means that if you run the python command within the test_env, the D:test_env.envScriptspython.exe will execute instead of C:pythonpython.exe.

Third, show the packages installed in the .venv virtual environment for the test_env project:

pip listCopy

Output:

Package Version
------- -------
pip     24.3.1Copy

When you created the .venv virtual environment, the venv module already installed the package pip.

Fourth, install the requests package in the virtual environment:

pip install requestsCopy

If you display all packages installed in the .venv virtual environment:

pip listCopy

you’ll see the requests package and its dependencies:

Package            Version
------------------ ---------
certifi            2025.1.31
charset-normalizer 3.4.1
idna               3.10
pip                24.3.1
requests           2.32.3
urllib3            2.3.0Copy

Fifth, create the requirements.txt file:

pip freeze > requirements.txtCopy

The content of the requirements.txt will look like this:

certifi==2025.1.31
charset-normalizer==3.4.1
idna==3.10
requests==2.32.3
urllib3==2.3.0Copy

The requirements.txt file contains all the packages with versions installed in the .venv virtual environment used for the project.

When you copy the project to a different machine, you can run the pip install command to install all the packages listed in the requirements.txt file using the following command:

pip install -r requirements.txtCopy

Sixth, create the main.py file that uses the requests module:

import requests

response = requests.get('https://www.google.com')
if response.status_code == 200:
    print(response.text)Copy

To run the main.py file, you can use the python command:

python main.pyCopy

This command executes the python.exe from the .venv and loads the packages installed in the .venv virtual environment.

To deactivate the virtual environment, you can run the deactivate command:

deactivateCopy

It’ll return the following:

D:test_env>Copy

Now, you don’t see the (.venv) prefix anymore. It means that you’re not in the .venv virtual environment.

Summary #

• A virtual environment creates an isolated environment for a Python project.
• Use the venv module to create a new virtual environment.

Quiz #