Velamuvi AIAcademy

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
In this lesson you will learn
  • 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 .venv

This 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/activate

The 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).

Try it yourselfPython
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

Practice exercise

Write the same check Python uses to tell whether a virtual environment is active.

Your solutionPython
# 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
Knowledge check

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 (py on Windows) inside the project folder.
  • Activate it with .venv\Scripts\activate on Windows or source .venv/bin/activate on macOS and Linux. The prompt shows (.venv).
  • Leave .venv out of Git, and share a requirements.txt instead.

Next: installing libraries into your environment with pip.

Finished reading? Tick it off to track your progress.