Modules & PackagesIntermediate⏱ 7 min48 / 63

Virtual Environments

Learn how to give each Python project its own private sandbox so package versions never clash.

Imagine you are a chef working in two different restaurants at the same time. One restaurant needs you to use salt from Brand A, and the other insists on Brand B. You cannot mix them up — each kitchen needs its own supplies.

Python projects work the same way. Project A might need version 1.0 of a library, while Project B needs version 3.0. If you install everything in one global pile, they will eventually conflict. Virtual environments give every project its own private kitchen — its own isolated set of packages.

See it in action

Visual walkthrough1 / 5
1

Every Project Gets Its Own Sandbox

Two projects can need different versions of the same package — and global installs can only hold one. Virtual environments give each project its own private space so versions never clash.

Think of it like phone apps: Instagram and WhatsApp each run in their own sandbox and can never break each other.

#The Problem: Global Package Chaos

When you first install Python, it comes with one global location where packages are stored. Every time you run pip install something, it lands there.

This seems fine at first — until you have two projects that need different versions of the same package. You cannot have both version 1 and version 3 installed globally at the same time. One of your projects will always break.

Think of it like

Think of it like apps on your phone

Each app on your phone runs in its own sandbox. Instagram cannot accidentally break WhatsApp because they share a file. Virtual environments do the same thing for Python projects — each one gets its own space.

#Creating a Virtual Environment

Python ships with a built-in tool called venv (short for virtual environment). You run it once inside your project folder and it creates a hidden folder — usually called .venv — that will hold all the packages for that project only.

This creates a .venv folder next to your project files. It only needs to be run once per project.
# Run this in your terminal, inside your project folder
python -m venv .venv
Note

Why the dot in .venv?

The leading dot (.venv) is a naming convention that marks the folder as hidden on macOS and Linux. It keeps your project folder tidy. You could name it anything, but .venv is the most common convention and many tools recognize it automatically.

#Activating the Environment

Creating the environment is not enough — you also need to activate it. Activation tells your terminal: "from now on, use the Python and pip inside .venv, not the global ones."

The command is slightly different depending on your operating system.

Pick the one that matches your OS. After running it, your terminal prompt will change to show (.venv) at the start.
# macOS or Linux — run this in your terminal
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
Tip

How do I know it worked?

After activating, your terminal prompt changes — it will show (.venv) at the beginning of the line, like this:

`` (.venv) your-computer:myproject you$ ``

That little label is your confirmation. You are now inside the sandbox.

#Installing Packages Inside the Environment

Once activated, pip install works exactly as you are used to — but now packages land inside `.venv` instead of the global location. They are completely isolated to this project.

pip list shows only the packages in THIS environment — a clean, short list instead of everything ever installed globally.
# With the environment activated, install a package normally
pip install requests

# Verify it installed
pip list

You can also save the list of your project's packages to a file so teammates (or your future self) can recreate the exact same environment:

`` pip freeze > requirements.txt ``

Then someone else can install everything in one command:

`` pip install -r requirements.txt ``

#Leaving the Environment

When you are done working on a project, you can step out of the environment with a single word. This returns your terminal to using the global Python.

The (.venv) label disappears from your prompt. You are back to the global Python.
# Exit the virtual environment
deactivate

#Keep .venv Out of Git

The .venv folder can contain thousands of files and take up megabytes of space. You should never commit it to Git. Instead, commit your requirements.txt — that tiny file tells anyone who clones your project exactly what to install.

Add .venv to your .gitignore file:

Add this to .gitignore at the root of your project. Git will ignore the entire .venv folder.
# Contents of your .gitignore file
.venv/
__pycache__/
*.pyc
Common mistake

Forgetting to activate before installing

A very common mistake: you create the environment, then run pip install without activating first. The package ends up in the global location, not inside .venv.

Always check for the (.venv) label in your terminal prompt before running pip install. If you do not see it, run the source .venv/bin/activate command first.

Watch out

Do not move the .venv folder

The paths inside .venv are hardcoded to your project's location. If you rename or move your project folder, the environment will break. Just delete .venv and run python -m venv .venv again — it only takes a few seconds.

#The Full Workflow at a Glance

This is the complete daily workflow. Steps 1 and 4 are one-time actions; steps 2, 3, and 5 happen every session.
# 1. Create the environment (once per project)
python -m venv .venv

# 2. Activate it (every time you start working)
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate.bat  # Windows

# 3. Install what you need
pip install requests pandas

# 4. Save your dependencies
pip freeze > requirements.txt

# 5. When done for the day
deactivate
Quick check

You just created a virtual environment with `python -m venv .venv`. You then run `pip install flask`. Where does Flask get installed?

Key takeaways

  • Virtual environments isolate each project's packages so version conflicts never happen.
  • Create one with `python -m venv .venv` — just once per project.
  • Always activate (`source .venv/bin/activate`) before installing or running code.
  • Use `pip freeze > requirements.txt` to share your dependencies without committing `.venv`.
  • Add `.venv/` to `.gitignore` — never commit the environment folder itself.
Practice challenges
Test yourself · earn XP
0/4
Predict the output#1

A developer runs these terminal commands in order. What does the prompt look like AFTER the third command succeeds?

predict-output
# Command 1
python -m venv .venv

# Command 2
source .venv/bin/activate

# Command 3
pip install requests
Fix the bug#2

A developer wants to install Flask into their virtual environment, but it ends up in the global Python location instead. What went wrong?

fix-bug
# In the terminal:
python -m venv .venv
pip install flask
Fill in the blank#3

Complete the two terminal commands: first to save the current environment's packages to a file, then to install from that file in a fresh environment.

# Save dependencies
pip  > requirements.txt

# Recreate the environment elsewhere
pip install  requirements.txt
Reorder the lines#4

Put these terminal commands in the correct order to set up and use a new virtual environment from scratch.

1
pip install pandas
2
pip freeze > requirements.txt
3
source .venv/bin/activate
4
python -m venv .venv
5
deactivate
Your turn
Practice exercise

Create a new folder called sandbox-project. Inside it, create a virtual environment, activate it, install the httpx package, then save your dependencies to requirements.txt. Finally, open requirements.txt and paste its contents as a comment in a Python file called notes.py.

Try it live — edit the code and hit Run to execute real Python:

solution.py · editable