Different Python projects may require different packages or different versions of the same package. Installing every dependency into one global Python installation can create package conflicts.

A virtual environment provides a separate Python environment for an individual project. Packages installed in one virtual environment do not normally affect packages installed in another environment.

Prerequisites

What is a Virtual Environment?

A virtual environment is a project-specific Python environment. It contains a Python executable, activation scripts, configuration information, and a separate location for installed packages.

Python provides the built-in venv module for creating lightweight virtual environments.

Why Use a Virtual Environment?

Example of a Version Conflict

Suppose two Python projects require different versions of the same package:

Separate virtual environments allow both projects to use their required versions without interfering with each other.

Check the Python Installation

Open your command-line application and check the installed Python version.

python --version

On some systems, use one of the following commands:

py --version

python3 --version

Example output:

Python 3.x.x

Create a Project Folder

First, create a separate folder for the Python project:

mkdir virtual-environment-demo

Move into the project folder:

cd virtual-environment-demo

Create a Virtual Environment

Use the following command to create an environment named .venv:

python -m venv .venv

On Windows, the Python launcher may also be used:

py -m venv .venv

On Linux or macOS, you may need to use:

python3 -m venv .venv

What Does venv Create?

The venv module creates a directory containing the files needed for the isolated Python environment.

Activate the Virtual Environment

Activation configures the current terminal to use the virtual environment's Python interpreter and package installation location.

Windows Command Prompt

.venv\Scripts\activate

Windows PowerShell

.venv\Scripts\Activate.ps1

Linux or macOS

source .venv/bin/activate

After activation, the environment name normally appears before the terminal prompt:

(.venv) project-folder

Verify the Active Environment

Use Python to display the active interpreter location:

python -c "import sys; print(sys.executable)"

The displayed location should contain the .venv directory.

Verify the pip installation:

python -m pip --version

The pip location should also belong to the active environment.

Install Packages in the Environment

After activating the environment, install the required package:

python -m pip install requests

Install multiple packages:

python -m pip install requests flask pytest

Display the installed packages:

python -m pip list

Check package compatibility:

python -m pip check

Successful compatibility check:

No broken requirements found.

Test the Environment

Create a file named app.py:

import requests

print("Requests version:", requests.__version__)
print("Virtual environment is working.")

Run the program:

python app.py

Possible output:

Requests version: 2.x.x
Virtual environment is working.

Save the Project Dependencies

Generate a requirements file containing the packages installed in the environment:

python -m pip freeze > requirements.txt

Example requirements.txt:

certifi==2025.4.26
charset-normalizer==3.4.2
idna==3.10
requests==2.32.3
urllib3==2.4.0

The dependency file can be used to recreate the environment on another computer.

Exclude the Environment from Git

The environment directory should not normally be committed to a version-control repository.

Add the following entry to the project's .gitignore file:

.venv/
__pycache__/
*.pyc

Deactivate the Environment

When you finish working on the project, leave the environment using:

deactivate

Deactivation does not delete the environment or remove its installed packages. It only returns the current terminal to its normal Python configuration.

Reactivate an Existing Environment

You do not need to create the environment again every time you open the project.

Navigate to the project folder and run the appropriate activation command:

.venv\Scripts\activate

For Linux or macOS:

source .venv/bin/activate

Recreate a Virtual Environment

A virtual environment should be considered reproducible. Instead of copying the complete environment directory, create a new environment and reinstall the recorded dependencies.

Create a new environment:

python -m venv .venv

Activate the environment and install the requirements:

python -m pip install -r requirements.txt

Verify the installed dependencies:

python -m pip check

Common Problems and Solutions

Best Practices

Complete Workflow

# Create the project folder
mkdir virtual-environment-demo

# Enter the project folder
cd virtual-environment-demo

# Create the environment
python -m venv .venv

# Activate the environment using the command for your system

# Verify Python
python -c "import sys; print(sys.executable)"

# Verify pip
python -m pip --version

# Install packages
python -m pip install requests flask pytest

# List packages
python -m pip list

# Check dependencies
python -m pip check

# Save dependencies
python -m pip freeze > requirements.txt

# Leave the environment
deactivate

Knowledge Check

python -m venv .venv

source .venv/bin/activate

deactivate

Virtual Environment Quick Reference

# Create an environment
python -m venv .venv

# Activate on Linux or macOS
source .venv/bin/activate

# Display the active interpreter
python -c "import sys; print(sys.executable)"

# Verify pip
python -m pip --version

# Install a package
python -m pip install requests

# Install from requirements.txt
python -m pip install -r requirements.txt

# List packages
python -m pip list

# Check dependencies
python -m pip check

# Save dependencies
python -m pip freeze > requirements.txt

# Leave the environment
deactivate

Summary