Lesson 13 of 16 · Project Setup
Virtual Environments
Learn what a Python virtual environment is, why every project needs one, and how to create, activate and remove one with venv on Windows, macOS and Linux.
- 8 min read
- Intermediate
- Reviewed
- What problem a virtual environment solves
- How to create and activate one on Windows, macOS and Linux
- How to tell whether one is active
- Which files to share and which to leave out
The problem
Imagine two projects on your computer:
- Project A, written last year, needs version 1 of a library.
- Project B, started today, needs version 2 of the same library.
If both projects share one Python installation, they share one copy of every library. Installing version 2 for Project B silently breaks Project A.
A virtual environment solves this. It is a private folder of libraries that belongs to one project. Each project gets its own, so they never interfere.
Your computer
├── Python (installed once)
├── project-a/
│ └── .venv/ ← library version 1 lives here
└── project-b/
└── .venv/ ← library version 2 lives here
Creating one
Open a terminal in your project folder and run Python's built-in venv module. By convention the folder is called .venv.
# Windows
py -m venv .venv
# macOS and Linux
python3 -m venv .venvThis creates a .venv folder containing a private copy of the Python program and an empty space for libraries. It takes a few seconds.
Activating it
Creating the environment is not enough. You activate it, so the terminal uses this project's Python and libraries.
# Windows (Command Prompt or PowerShell)
.venv\Scripts\activate
# macOS and Linux
source .venv/bin/activateThe prompt now starts with (.venv). That is your sign that the environment is active.
(.venv) C:\Users\ada\project-b>From now on, python runs the environment's Python and anything you install goes into .venv, not into your whole computer.
When you are finished, type deactivate to leave the environment. Activation only lasts for that terminal window, so you activate again each time you open a new one.
Checking from Python
Inside a virtual environment, sys.prefix (where Python is running from) differs from sys.base_prefix (where Python was installed).
import sys
print("Python is running from:", sys.prefix)
print("Inside a virtual environment:", sys.prefix != sys.base_prefix)In this browser editor the answer is False, because there is no virtual environment here. On your computer, with .venv active, it prints True.
Editors do this for you
Visual Studio Code notices a .venv folder in your project and offers to use it. Choose it once, and every terminal and every Run button in that project uses the environment automatically. Most other editors work the same way.
What to share, and what not to
The .venv folder is big and specific to your computer. Never put it on GitHub or send it to anyone. Instead, you share a short list of the libraries the project needs, called requirements.txt, and others create their own environment from it. The next lesson shows how.
Add this line to your project's .gitignore file, so Git ignores the folder:
.venv/If an environment gets into a mess, you can simply delete the .venv folder and create a fresh one. Your code is not inside it.
Common mistakes
Write the same check Python uses to tell whether a virtual environment is active.
# A virtual environment is active when the folder Python runs from (prefix)
# is different from where Python was installed (base_prefix).
# Write a function in_virtual_env(prefix, base_prefix) that returns True or False.
print(in_virtual_env("/home/ada/project/.venv", "/usr"))
print(in_virtual_env("/usr", "/usr"))
# Output must be exactly:
# True
# False
Why does each project get its own virtual environment?
Summary
- A virtual environment is a private set of libraries for one project.
- Create it with
python -m venv .venv(pyon Windows) inside the project folder. - Activate it with
.venv\Scripts\activateon Windows orsource .venv/bin/activateon macOS and Linux. The prompt shows(.venv). - Leave
.venvout of Git, and share arequirements.txtinstead.
Next: installing libraries into your environment with pip.
Finished reading? Tick it off to track your progress.