Skip to content
Tutorials Center
My learning

Topics

Lesson 88 of 149 ยท Beyond the Basics

Virtual Environments and Project Setup

Set up real Python projects. Create virtual environments with venv, install packages with pip, pin requirements, lay out folders and describe it all in pyproject.toml.

So far every example has run in this browser editor, where Python is ready the moment you press Run. Real projects live on your own computer, and they quickly need third-party packages: a web framework here, a data library there. Install them all into one global Python and, sooner or later, two projects will need different versions of the same package and one of them will break.

Virtual environments solve that. Each project gets its own private set of installed packages, separate from every other project and from the system Python. In this lesson you will learn what a virtual environment really is, create and use one with venv, record your dependencies, organize a project's folders and describe it in a pyproject.toml file.

Most of this lesson happens in a terminal on your machine, so the commands are shown as read-only code. The live editors let you peek at the same ideas from inside Python.

The problem: one Python, many projects

Imagine two projects on one laptop:

  • An older reporting tool that only works with version 1 of a library.
  • A new web app that needs version 2 of the same library.

If both use the one global Python, only one version can be installed at a time. Upgrading for the web app silently breaks the reporting tool. On top of that, installing packages into the system Python can interfere with tools your operating system relies on, which is why many Linux distributions and macOS's Homebrew Python now refuse a plain pip install outside a virtual environment.

A virtual environment gives each project its own site-packages folder (where installed packages go), so versions never collide.

What a virtual environment is

A virtual environment is just a folder. Inside it are:

  • a small python launcher that points back to the Python you created it from,
  • an empty site-packages folder for this project's packages,
  • a pyvenv.cfg file recording which Python it came from,
  • activation scripts for your shell.

When Python starts from that folder, it sets sys.prefix to the environment's folder, while sys.base_prefix still points to the original installation. Comparing the two is the standard way to ask "am I in a virtual environment?":

Python Where is this Python running?

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.

In this browser editor the answer is False: there is only one Python here, compiled for the web. Run the same code on your computer before and after activating an environment and you'll see the prefix change.

Imports are found by searching the folders in sys.path, in order. A virtual environment works by putting its own site-packages on that list:

Python Where imports come from

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.

Creating and using an environment

Python includes the venv module for creating environments. By convention the folder is named .venv and lives inside the project folder. In a terminal:

TEXT
cd my-project
python -m venv .venv

On Windows, use py -m venv .venv if python isn't on your PATH. Next, activate it. This adjusts your shell so that python and pip refer to the environment:

TEXT
# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# macOS and Linux
source .venv/bin/activate

Your prompt usually changes to show (.venv). Now everything you install goes into this project only:

TEXT
(.venv) python -m pip install requests
(.venv) python -m pip list
(.venv) deactivate

deactivate returns the shell to normal. Activation is a convenience, not a requirement: running .venv/bin/python script.py (or .venv\Scripts\python.exe on Windows) uses the environment directly. Most editors, including VS Code and PyCharm, detect a .venv folder and use it automatically.

Use python -m pip instead of plain pip. It guarantees that pip installs into the same Python you are running, which avoids the classic "I installed it but Python can't find it" mystery.

Never commit .venv to version control. It contains thousands of files built for your exact operating system. Add .venv/ to .gitignore and commit the list of dependencies instead, so anyone can rebuild the environment in one command.

Recording your dependencies

An environment is disposable: you should be able to delete .venv and rebuild it at any time. That only works if the list of packages is written down. The traditional place is a requirements.txt file:

TEXT
# requirements.txt
requests>=2.31,<3
rich==13.7.1

Each line is a package name, optionally with a version specifier:

Specifier Meaning
==1.4.2 exactly this version (a "pin")
>=2.31 this version or newer
>=2.31,<3 at least 2.31 but below 3.0
~=1.4.2 compatible release: at least 1.4.2, below 1.5

Install everything on the list with:

TEXT
python -m pip install -r requirements.txt

python -m pip freeze prints every package installed in the current environment with its exact version. Saving that output (pip freeze > requirements.txt) captures a reproducible snapshot, including packages your packages depend on.

Python can also tell you what's installed through importlib.metadata. In this browser runtime the list is short; in a real environment you'll see everything you installed:

Python Asking which packages are installed

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.

Project structure

A clean layout makes a project easy to navigate, test and package. A widely used shape is the src layout:

TEXT
weather-cli/
  .venv/                  # not committed
  .gitignore
  README.md
  pyproject.toml          # project metadata and dependencies
  src/
    weather_cli/
      __init__.py         # makes the folder a package
      __main__.py         # runs with: python -m weather_cli
      forecast.py
  tests/
    test_forecast.py
  • The importable code lives in a package folder (see Modules and Imports and Packages and pip) whose name uses underscores, while the project name can use hyphens.
  • Putting it under src/ ensures your tests import the installed package rather than a stray file from the current folder.
  • tests/ holds the tests you learned to write in Testing with unittest and doctest.

Here is that skeleton built in the editor's temporary in-memory file system with pathlib, then printed as a tree:

Python Scaffolding a project

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.

pyproject.toml

Modern Python projects describe themselves in a single pyproject.toml file. It is written in TOML, a simple configuration format, and replaces older files like setup.py for most projects. A typical one looks like this:

TOML
[project]
name = "weather-cli"
version = "0.1.0"
description = "Show the forecast in your terminal"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "httpx>=0.27",
    "rich>=13",
]

[project.optional-dependencies]
dev = ["pytest>=8"]

[project.scripts]
weather = "weather_cli.__main__:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
  • [project] holds the name, version, supported Python versions and runtime dependencies.
  • optional-dependencies groups extras such as development tools, installed with pip install -e ".[dev]".
  • [project.scripts] creates a terminal command (weather) that calls a function in your package.
  • [build-system] tells pip which tool builds the package.

With this file in place, python -m pip install -e . installs your project into the active environment in editable mode: your code changes take effect immediately, without reinstalling.

Python reads TOML with the built-in tomllib module (3.11+), so you can inspect a configuration from code:

Python Reading pyproject.toml with tomllib

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.

tomllib only reads TOML; it can't write it. To load a real file, open it in binary mode: with open("pyproject.toml", "rb") as f: config = tomllib.load(f).

Other tools you'll meet

venv and pip are built in and always available, so learn them first. The wider ecosystem offers tools that bundle these steps together:

  • uv: a very fast installer and project manager that creates environments, resolves dependencies and writes a lock file.
  • Poetry and PDM: project managers built around pyproject.toml with lock files.
  • pipx: installs command-line tools (like formatters) each in its own isolated environment.
  • conda: an environment and package manager popular in data science, which can also install non-Python libraries.

They all rely on the same ideas you learned here: one isolated environment per project, dependencies declared in a file, and environments you can throw away and rebuild.

A checklist for every new project

  1. Create a folder and a .venv inside it: python -m venv .venv.
  2. Activate the environment (or point your editor at it).
  3. Add a .gitignore that excludes .venv/ and __pycache__/.
  4. Write a pyproject.toml (or at least a requirements.txt) as you add dependencies.
  5. Put code in a package folder and tests in tests/.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the main purpose of a virtual environment?

    Each environment has its own site-packages folder, so projects can use different package versions without conflicts.
  2. 2. Which command creates a virtual environment in a folder named .venv?

    The built-in venv module creates the environment; the last argument is the folder to create.
  3. 3. Which comparison tells you that the running Python is inside a virtual environment?

    Inside an environment, sys.prefix points to the environment folder while sys.base_prefix still points to the original installation.
  4. 4. What should you commit to version control?

    Commit the list of dependencies so anyone can rebuild the environment. The .venv folder is machine-specific and should be ignored.
  5. 5. What does the specifier ~=1.4.2 allow?

    ~= is the compatible-release operator: patch updates are allowed, but not the next minor version.

Summary

  • A virtual environment is a folder with its own site-packages, so each project has isolated packages.
  • Create one with python -m venv .venv, activate it, and install with python -m pip install ....
  • sys.prefix != sys.base_prefix tells you that you're inside an environment; sys.path shows where imports are searched.
  • Record dependencies in requirements.txt or, better, in pyproject.toml; never commit .venv.
  • Organize code as a package (often under src/) with tests in tests/; tools like uv, Poetry and pipx build on the same ideas.

Next: Command-Line Programs with argparse.