Virtual Environments

Soon you will install packages that other people wrote. If every project on your computer installs into the same Python, one project's upgrade can break another, and after a year nobody can say which project needed what. A virtual environment solves this: a private folder of packages for one project, created with a single command and thrown away just as easily.

Think of keeping a separate toolbox for each job. The plumbing kit does not get mixed up with the woodworking kit, you can take one to a friend's house without the other, and emptying one never touches the rest.

The Problem

Imagine two projects. One needs version 2 of a package; the other was written for version 3, which works differently. With one shared installation there is room for only one version, so whichever you install, one project breaks. Nothing in the error message will say "because of the other project". Separate environments make the conflict impossible.

Making One

Inside your project folder, run the venv module that comes with Python and give it a name for the new folder. By convention the name is .venv, with a dot at the front. The command creates that folder: a small structure that points at the Python you already have, with an empty place for packages. It takes a few seconds and prints nothing.

you@mac python-course % python3 -m venv .venv
you@mac python-course %

PS C:\Users\you\python-course> python -m venv .venv
PS C:\Users\you\python-course>

The -m means "run this module as a program", and it is how this book runs Python's own tools: python -m venv here, python -m pip in the next topic, python -m pytest in Chapter 12.

Activating It

A virtual environment is used by activating it in a terminal. On a Mac, run source .venv/bin/activate. On Windows, in PowerShell, run the script .venv\Scripts\Activate.ps1. Either way, the prompt changes to start with the environment's name in brackets, which is how you can tell at a glance that it is active.

you@mac python-course % source .venv/bin/activate
(.venv) you@mac python-course % python --version
Python 3.15.0

PS C:\Users\you\python-course> .venv\Scripts\Activate.ps1
(.venv) PS C:\Users\you\python-course> python --version
Python 3.15.0

On Windows, the first attempt may be refused with a message that running scripts is disabled on this system. That is a PowerShell safety setting, not a problem with Python. The Python documentation gives the one-time fix: run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser in PowerShell, answer yes if asked, and activate again. It changes the setting for your user account only.

Inside, python Is python

Look at the command in the last two blocks: python, on both systems. Inside an active environment, python means that environment's Python, on a Mac too. From here on this book writes python everywhere, and assumes an environment is active whenever a package is involved.

Activation lasts for that terminal window. Close the window, or type deactivate, and the prompt loses its brackets. Open a new terminal tomorrow and you activate again.

What Not to Do with It

The .venv folder is disposable. Never edit files inside it, never put your own code in it, and never send it to anyone or save it in a backup of your project: it can always be deleted and recreated from scratch. The list of packages the project needs is what you keep, and the next topic shows how.