Python Virtual Environments (venv) : Setup Guide & Why Use Them

Imagine you are building two different applications on your computer. Project A is an older web scraper that relies on an older version of a tool (like version 1.0), while Project B is a brand-new data visualization app that strictly requires the newest version of that exact same tool (version 2.0).

If you install Python packages globally—meaning directly onto your computer’s main operating system—installing version 2.0 for Project B will overwrite version 1.0. Suddenly, Project A completely breaks! This nightmare scenario is famously known in the programming world as dependency hell.

To solve this, Python developers use Virtual Environments (venv). A virtual environment is a self-contained, isolated directory that holds its own unique installation of Python and its own independent set of installed packages. By creating a specific virtual environment for every new project, you ensure that upgrading or removing a package in one project will never affect your other projects.

Prerequisites

Before setting up your virtual environment, you will need:

The Python interpreter successfully installed on your machine (refer to Chapter 1.2).
A basic understanding of how to open and type in your computer’s Terminal (macOS/Linux) or Command Prompt / PowerShell (Windows).

Step-by-Step Installation & Setup Guide

Python comes with a built-in module called venv specifically designed for creating these isolated spaces. Setting one up is a fast, standardized process across all operating systems.

Step 1: Open Your Terminal and Navigate to Your Project

First, open your terminal and navigate to the folder where you want to build your Python project.

Step 2: Create the Virtual Environment

To create the environment, we use the python -m venv command followed by the name we want to give our environment. The industry standard is usually naming it venv or env, but let’s use a descriptive name here.

# TERMINAL COMMAND: Create a new virtual environment
# Note: Type these commands in your terminal, not in a Python code file!
python -m venv project_workspace_env

# Expected Output:
# (No output means it was successful. A new folder named 'project_workspace_env' 
# will appear inside your current directory, containing the isolated Python setup.)
Code language: PHP (php)

Step 3: Activate the Virtual Environment

Creating the environment isn’t enough; you must activate it. This tells your computer, “Hey, for any Python commands I run from now on, use the isolated environment I just created, not the global one.”

The activation command is the only step that differs based on your operating system:

# TERMINAL COMMAND: Activate the environment on Windows
project_workspace_env\Scripts\activate

# TERMINAL COMMAND: Activate the environment on macOS / Linux
source project_workspace_env/bin/activate

# Expected Output:
# Your terminal prompt will change to show the environment name in parentheses.
# Example: (project_workspace_env) C:\Users\Developer\MyProject>
Code language: PHP (php)

[Insert Screenshot of a terminal showing an active virtual environment in parentheses]

Step 4: Work Inside the Environment

While the environment is active, any packages you install using Python’s package manager (pip) will be trapped safely inside this specific project_workspace_env folder.

Step 5: Deactivate the Environment

When you are completely done working on this project for the day and want to return to your computer’s normal, global Python environment, you simply deactivate it.

# TERMINAL COMMAND: Leave the virtual environment
deactivate

# Expected Output:
# The (project_workspace_env) tag will disappear from your terminal prompt, 
# indicating you are back to your standard system environment.
Code language: PHP (php)

Verifying the Setup

How can you be absolutely sure that your virtual environment is active and successfully isolating your tools? You can ask your computer to show you exactly which Python it is currently using.

Make sure your environment is activated, then run the following command based on your OS:

# TERMINAL COMMAND: Verify the active Python path

# On Windows:
where python

# On macOS / Linux:
which python

# Expected Output:
# The terminal should print a path pointing directly inside your new project folder.
# Example: C:\Users\Developer\MyProject\project_workspace_env\Scripts\python.exe
Code language: PHP (php)

If it points to your main system folder (like C:\Program Files\Python), your environment is not activated!

Common Errors & Troubleshooting

Error: “Execution of scripts is disabled on this system” (Windows PowerShell)
- The Fix: Windows has strict default security policies. To fix this, open PowerShell as Administrator and run the command: Set-ExecutionPolicy Unrestricted -Force. Close the terminal, reopen your project, and try activating the environment again.
Error: “The virtual environment was not created successfully because ensurepip is not available” (Ubuntu / Debian Linux)
- The Fix: Some Linux distributions strip the venv module out of the default Python installation to save space. You can easily fix this by installing it manually. Run: sudo apt install python3-venv.
Error: “python: command not found” (macOS / Linux)
- The Fix: Remember that on macOS and Linux, you often need to explicitly type python3 instead of python. Try creating your environment using python3 -m venv project_workspace_env instead.

Summary

Dependency hell occurs when different Python projects require conflicting versions of the same software packages.
Virtual Environments (venv) solve this by creating an isolated, sandbox folder for every single project you build.
Creating an environment requires running python -m venv my_environment_name in your terminal.
You must activate the environment before working, which is done differently on Windows vs. Mac/Linux.
When you are done coding, simply type deactivate to close the sandbox.

Now that your workspace is clean, isolated, and professional, you are finally ready to write and execute your very first lines of Python code!