Creating a Python Virtual Environment (venv): A Step-by-Step Guide

Managing Python dependencies can quickly become overwhelming when juggling multiple projects. Different libraries and versions often lead to compatibility issues—this is where virtual environments come in handy. In this blog, you’ll learn how to create and manage isolated python virtual environment (venv) using the built-in venv module.

Whether you're working on a data science project, web app, or automation script, this guide will help you keep your development setup clean and conflict-free.

What Is a Virtual Environment in Python?

A virtual environment is a self-contained directory that includes its own Python interpreter and a local pip installation, completely isolated from the global Python setup on your system. This means every project can operate in its own dedicated environment with its own dependencies, ensuring clean separation and better project management.

This is especially important when:

• You need to work with different versions of the same library across multiple projects

• You're contributing to a project that requires specific package versions

• You want to avoid breaking existing code by installing new packages globally

• You plan to distribute your project and want to document dependencies cleanly

Using virtual environments allows you to:

• Use different library versions for each project

• Prevent package conflicts and version mismatches

• Easily share and recreate project environments using a requirements.txt file

• Experiment safely with packages and roll back without affecting your global Python setup

Whether you're developing a machine learning model, building a web application, or automating tasks with scripts, virtual environments provide a controlled and reproducible workspace.

Prerequisites

• Python 3.3 or later installed

• A terminal or command prompt

• Basic command line knowledge

  
  

You can check your Python version with:

python3 --version

Output:
Python 3.13.3

How to Create a Python Virtual Environment (venv)

Creating a virtual environment in Python allows you to isolate project-specific dependencies and avoid conflicts with global packages. In this quick guide, you’ll learn how to use Python’s built-in venv module to set up a clean, manageable development environment for any Python project.

Step 1: Navigate to Your Project Directory

Begin by opening a terminal and navigating to the directory where your project is located. If the project folder does not already exist, you can create it before proceeding.

cd path/to/your/project

All files associated with the virtual environment will be created inside this directory, helping keep your project organized and self-contained.

Step 2: Create the Virtual Environment

Once you're inside the project directory, create a virtual environment using the following command:

python3 -m venv env

Here, env is the name of your virtual environment folder. You can name it anything you like, but env or .venv are common conventions.

This command creates:

• A bin/ or Scripts/ directory with a local Python interpreter

• A lib/ directory with site-packages

• A pyvenv.cfg file to track the environment

Step 3: Activating the Virtual Environment

After creating the environment, it must be activated before you can begin installing packages and running project-specific Python code.

On macOS/Linux:

source env/bin/activate

Output:

(env) Samul@Samul-Mac-mini python-env % 

On Windows (CMD):

env\Scripts\activate

On Windows PowerShell:

.\env\Scripts\Activate.ps1

Once activated, your terminal prompt will display the environment name in parentheses, such as (env). This indicates that all Python commands and package installations are now isolated within the virtual environment rather than being installed globally on your system.

Step 4: Installing Packages Inside the Environment

After activating your virtual environment, you can install packages using pip just as you would in a regular Python environment. The difference is that the packages will be installed only within the virtual environment, ensuring they remain isolated from other projects and your system-wide Python installation.

For example, to install popular libraries such as NumPy, Pandas, and Flask, run:

pip install numpy pandas flask

Output:

...
Collecting werkzeug>=3.1.0 (from flask)
  Downloading werkzeug-3.1.3-py3-none-any.whl.metadata (3.7 kB)
Collecting six>=1.5 (from python-dateutil>=2.8.2->pandas)
  Downloading six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
Downloading numpy-2.3.1-cp313-cp313-macosx_14_0_arm64.whl (5.1 MB)
   ━━━━━━━━━━━━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━ 2.4/5.1 MB 102.0 kB/s eta 0:00:27
...

Once installed, the packages become available immediately within the active virtual environment.

To view all installed packages and their versions, use:

pip list

Output:

Package         Version
--------------- -----------
blinker         1.9.0
click           8.2.1
Flask           3.1.1
itsdangerous    2.2.0
Jinja2          3.1.6
MarkupSafe      3.0.2
numpy           2.3.1
pandas          2.3.1
pip             25.0.1
python-dateutil 2.9.0.post0
pytz            2025.2
six             1.17.0
tzdata          2025.2
Werkzeug        3.1.3

As projects grow, keeping track of dependencies becomes increasingly important. Python developers commonly store package requirements in a requirements.txt file, making it easy to recreate the same environment on another machine.

To save all installed packages and their versions to a requirements file, run:

pip freeze > requirements.txt

This generates a complete list of dependencies currently installed in the virtual environment.

Later, if you need to recreate the environment or share the project with others, the packages can be installed using:

pip install -r requirements.txt

This ensures that everyone working on the project uses the same package versions, reducing compatibility issues and improving reproducibility.

Step 5: Deactivating the Virtual Environment

When you finish working on your project, you can deactivate the virtual environment and return to your system's default Python installation by running:

deactivate

After executing this command, the environment name will disappear from your terminal prompt, indicating that the virtual environment is no longer active. Any subsequent Python or pip commands will use the system-wide Python installation until another virtual environment is activated.

Using deactivate does not delete the virtual environment—it simply exits it. You can reactivate the environment at any time using the appropriate activation command for your operating system.

Optional: Ignore env/ in Git Projects

Virtual environments contain installed packages, executables, and other generated files that can be recreated at any time. Because of this, they should generally not be committed to version control systems such as Git. Including them in a repository can significantly increase its size and introduce unnecessary files that other developers do not need.

To prevent your virtual environment from being tracked, add the following entry to your .gitignore file:

env/

This keeps your Git repositories clean and avoids pushing unnecessary binaries. If you're using .venv as the environment name, add:

.venv/

This ensures that Git ignores the entire virtual environment directory, keeping your repository clean and focused on source code rather than generated dependencies.

Why Use venv Instead of Global Python?

Installing packages globally may seem convenient at first, but it can quickly lead to dependency conflicts as projects grow. Different projects often require different package versions, and installing everything into a single global environment can cause compatibility issues that are difficult to diagnose and resolve.

Virtual environments solve this problem by creating isolated Python installations for each project. This separation provides several important advantages.

When using global Python installations, package conflicts are common because all projects share the same dependencies. With a virtual environment, each project maintains its own independent set of packages, eliminating interference between projects.

Dependency management also becomes significantly easier. Virtual environments work seamlessly with requirements.txt files, allowing developers to recreate the exact package configuration on another machine with a single command.

Project cleanup is another major benefit. Removing a project that uses global packages often requires manually identifying and uninstalling dependencies. With a virtual environment, you can simply delete the environment folder and all associated packages are removed instantly.

Virtual environments also improve collaboration. Since every team member can install the same dependencies from a requirements file, development environments remain consistent and predictable across different systems.

Conclusion

Using a Python virtual environment is one of the most important best practices in modern Python development. By isolating dependencies at the project level, virtual environments help prevent package conflicts, improve reproducibility, and create a cleaner development workflow.

Whether you're building web applications with frameworks such as Flask, Django, or FastAPI, or working on data science and machine learning projects with NumPy, Pandas, and scikit-learn, setting up a virtual environment should be one of the first steps in your workflow.

With only a handful of commands, you can create an isolated, reproducible, and maintainable development environment that scales from simple scripts to large production applications.