Two Python projects can easily need different versions of the same package. A virtual environment solves this by giving each project its own private set of packages. By the end of this guide, you will be able to create one with Python’s built-in venv module, turn it on and off, install packages into it and rebuild it on another computer.

The steps follow the venv reference page and the virtual environments chapter of the Python tutorial. The commands were run with Python 3.14 on macOS, and the output shown is real.

Why virtual environments exist

The tutorial gives a simple case. If application A needs version 1.0 of a module and application B needs version 2.0, one Python installation cannot satisfy both. A virtual environment is a self-contained folder with its own Python interpreter and packages, so each application can have the version it needs. Upgrading a library in one environment does not affect the other.

1. Create the environment

Open a terminal in your project folder and run:

python3 -m venv .venv

On Windows, the reference page runs it as python -m venv instead. The environment uses the same Python version as the interpreter that ran the command. The tutorial calls .venv a common name: it stays hidden in most shells, explains itself and does not clash with .env settings files. Listing the new folder shows what venv made:

$ ls -A .venv
.gitignore
bin
include
lib
pyvenv.cfg

pyvenv.cfg records which Python installation the environment came from. bin (called Scripts on Windows) holds the environment’s own python, and lib holds a site-packages folder where installed packages go. Since Python 3.13, venv also writes a .gitignore file so Git leaves the environment out of your repository.

2. Activate it

Activation points your terminal at the environment’s Python. The command depends on your system:

  • macOS or Linux (bash or zsh): source .venv/bin/activate
  • Windows Command Prompt: .venvScriptsactivate.bat
  • Windows PowerShell: .venvScriptsActivate.ps1

Your prompt now begins with (.venv), the environment’s folder name. Behind the scenes, activation puts the environment’s bin or Scripts folder at the front of your PATH, so typing python runs the environment’s interpreter.

3. Check that it worked

The reference page says that comparing sys.prefix with sys.base_prefix is enough to tell whether Python is running inside a virtual environment. Save this as check_env.py:

import sys
print(sys.prefix != sys.base_prefix)

Run it with the system Python, then with the environment’s Python:

$ python3 check_env.py
False
$ .venv/bin/python check_env.py
True

The second command also shows that activation is optional. Calling the environment’s interpreter by its path uses the environment directly.

4. Install and record packages

With the environment active, install packages through pip, as the tutorial does:

python -m pip install requests
python -m pip list
python -m pip freeze > requirements.txt

In a brand-new environment, pip list shows only pip itself. On the test machine it printed:

Package Version
------- -------
pip     26.2.1

pip freeze lists the installed packages and their versions in the format pip can read back. The tutorial describes the common convention of saving it as requirements.txt and committing that file to version control. Anyone can then rebuild the same set of packages with python -m pip install -r requirements.txt.

5. Deactivate it

Type deactivate to return your terminal to the system Python. The environment folder stays where it is, ready for next time.

Common mistakes

  • Committing the environment to Git. The reference page says environments are not checked into source control. Commit requirements.txt instead. On Python versions before 3.13, add .venv/ to your project’s .gitignore yourself.
  • Moving or copying the folder. Scripts inside an environment contain absolute paths to its interpreter, so an environment is not portable. To move a project, delete the old environment and create a new one in the new place.
  • Saving your code inside .venv. The documentation treats an environment as disposable, something you can delete and recreate at any time. Keep your own files outside it.
  • Installing before activating. Run pip only after activating, or through the environment’s own interpreter, so packages land in the environment.
  • PowerShell refusing to run Activate.ps1. The reference page says Windows may require you to allow local scripts first with Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser.

A virtual environment takes one command to create and one to activate, and it keeps every project’s packages separate. Create one per project, keep requirements.txt up to date, and treat the .venv folder as something you can rebuild whenever you need to.