Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 38 ยท Virtual Environments

Creating Environments with venv

Create and use virtual environments with python -m venv, activate them on every shell, read pyvenv.cfg, and understand virtualenv and common mistakes.

The standard library's venv module is the most portable way to make an environment. It ships with Python (on Debian and Ubuntu you may need the python3-venv package), needs no installation and works everywhere. This lesson covers the commands, what they create and the traps people fall into.

A note on this site: the browser's Python build removes the venv module because it cannot start processes or create symlinks. The commands are therefore read-only, and the live examples reproduce the files venv writes so you can see exactly what it does.

Create, activate, use, leave

Terminal
cd my-project
python3.12 -m venv .venv          # create (uses the Python you name)

source .venv/bin/activate         # Linux, macOS (bash/zsh)
.venv\Scripts\activate.bat        # Windows cmd
.venv\Scripts\Activate.ps1        # Windows PowerShell
source .venv/bin/activate.fish    # fish

(.venv) $ python -m pip install requests
(.venv) $ python -c "import sys; print(sys.prefix)"
(.venv) $ deactivate              # leave the environment

The name .venv is a strong convention. Editors such as VS Code and PyCharm look for it automatically, and .venv is already in most .gitignore templates. Some people use venv; avoid spaces and avoid names that clash with your package.

On PowerShell you may have to allow scripts once per user (Set-ExecutionPolicy -Scope CurrentUser RemoteSigned). Skipping activation and calling .venv\Scripts\python.exe directly avoids the whole issue.

Useful options

Terminal
python -m venv .venv --upgrade-deps        # upgrade pip right away
python -m venv .venv --system-site-packages # also see the system's packages
python -m venv .venv --without-pip         # skip bootstrapping pip
python -m venv .venv --clear               # empty an existing environment first
python -m venv .venv --prompt "api"        # custom prompt label
python -m venv .venv --copies              # copy the interpreter instead of linking

What venv writes

Three things matter: a pyvenv.cfg file, a launcher, and an empty site-packages into which pip is bootstrapped. The config file is a tiny INI-like text.

Python Reproducing the files venv creates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

When the interpreter starts, site looks for pyvenv.cfg next to the executable, or one directory up. If it finds one, sys.prefix becomes the environment directory and sys.base_prefix becomes home's parent. That is the whole trick: no copied standard library, no magic, just a marker file and a different prefix.

Activation, demystified

activate does three small things: prepends the environment's script directory to PATH, sets VIRTUAL_ENV, and changes your prompt. deactivate undoes them. You can reproduce the first effect with a few lines.

Python What activation does to PATH

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

That explains the most common "my venv does not work" report: which python still shows /usr/bin/python. Either the activate script was not sourced (running ./activate instead of source activate does nothing) or another tool re-ordered PATH afterwards.

virtualenv and friends

virtualenv is the older third-party tool that venv was based on. It is faster at creating environments (it caches wheels for pip and setuptools), can target other interpreters by version (virtualenv -p python3.9), and powers tox and nox. For daily work venv is enough. uv venv creates the same standard layout in milliseconds, which you will see in the next lesson.

Common mistakes

  • Moving or renaming the folder. Scripts inside contain absolute paths. Recreate instead.
  • Installing with the wrong pip. Use python -m pip after activating, or call .venv/bin/python -m pip.
  • Creating the environment from a different Python than intended. python3.12 -m venv fixes the version; the environment can never change it. To change versions, delete and recreate.
  • Committing .venv or site-packages. Ignore them.
  • Activating inside a container or CI step and expecting it to persist to the next step. Each step is a fresh shell; call the interpreter by path.
  • A name clash. A file venv.py or a folder venv that is not an environment breaks python -m venv.
Python A tiny checker for common environment mistakes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Never pip install anything while an environment is not active and you have not named one explicitly. If the prompt has no (.venv) prefix, you are probably about to change the global Python.

A reliable workflow

  1. python3.12 -m venv .venv
  2. .venv/bin/python -m pip install -U pip
  3. .venv/bin/python -m pip install -r requirements.txt (or -e .)
  4. Run tools with .venv/bin/python -m <tool>.
  5. Delete .venv and repeat when in doubt.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file marks a directory as a virtual environment and records the base interpreter?

    pyvenv.cfg holds home, include-system-site-packages and version. Python looks for it at startup.
  2. 2. You moved your project folder and the old .venv now misbehaves. What is the best fix?

    Environments hold absolute paths. Recreating is fast and reliable.
  3. 3. Which command is the most reliable way to install a package into .venv without activating it?

    Calling the environment's interpreter with -m pip leaves no doubt about the target.
  4. 4. What does activating an environment change?

    Activation is just environment-variable convenience; the interpreter works without it.

Summary

  • Create with python -m venv .venv, activate with the script for your shell, leave with deactivate.
  • pyvenv.cfg makes Python set sys.prefix to the environment and sys.base_prefix to the base.
  • Activation only edits PATH, VIRTUAL_ENV and the prompt.
  • Calling .venv/bin/python directly is the most reliable form, especially in scripts and CI.
  • Never move, commit or hand-edit environments; recreate them.
  • virtualenv is a faster, more flexible alternative; uv venv is faster still.

Next: uv and Modern Environment Management