pip installs Python packages, and venv builds the isolated environment that they go into. Used together, they make dependency management predictable. Every project gets its own set of libraries, every library version is written down in a file that you can commit, and an environment that breaks becomes a two-command fix instead of a complete reinstall of everything on your machine.
The previous lesson in this module covered "Structuring a Package: __init__.py and Layouts", and the next lesson in this module is about "Type Hints: Annotations That Pay Off".
Why does every Python project need its own virtual environment?
A virtual environment is a folder that contains its own copy of the interpreter paths and its own site-packages directory. When you activate it, Python stops looking at the system libraries and looks only inside that folder. Two projects can therefore ask for completely different versions of the same package without arguing with each other.
You can detect a virtual environment from inside Python, and that is the check that is worth putting into any setup script or debugging session.
import sys
print('executable:', sys.executable)
print('prefix:', sys.prefix)
print('base prefix:', sys.base_prefix)
print('inside a venv:', sys.prefix != sys.base_prefix)
Outside a virtual environment the two prefix values are the same, so the last line prints False. Inside one, sys.prefix points at the environment folder while sys.base_prefix still points at the interpreter that created it, so the last line prints True.
# Create it. One folder, one command, and no admin rights needed.
python -m venv .venv
# Activate it on Windows PowerShell.
.venv\Scripts\Activate.ps1
# Activate it on macOS and Linux.
source .venv/bin/activate
# Confirm that it worked.
python -c "import sys; print(sys.prefix != sys.base_prefix)"
# Leave it again.
deactivate
Use python -m venv rather than plain venv. The -m form guarantees that the environment is created by the same interpreter that you are about to use, and that matters the moment you have several Python versions installed on the machine.
How do you install packages without breaking the environment?
Inside an activated environment, install with python -m pip install. The -m form ties the installer to the interpreter that you are holding, so there is no chance of pip belonging to one Python while your script runs under a different one.
python -m pip install requests
python -m pip install "requests==2.32.3"
python -m pip install --upgrade pip
python -m pip uninstall requests
Three rules cover most of the damage that people do to their machines. Never install packages system-wide with sudo pip install, because that writes into the operating system's own Python and breaks other tools. Never mix pip with conda or poetry in the same environment, because each of them has its own resolver and they will fight each other. And on Debian or Ubuntu the system Python is marked as externally managed, so pip refuses to install into it and points you at a virtual environment instead. That refusal is protecting you and not blocking you.
You can also audit what an environment already contains without leaving Python.
from importlib.metadata import distributions, version
installed = []
for package in distributions():
name = package.metadata['Name']
if name and name not in installed:
installed.append(name)
installed.sort()
print('distributions installed:', len(installed))
print('first five:', installed[:5])
print('pip version:', version('pip'))
The count depends entirely on your machine. A bare interpreter has a handful of packages, and a working project environment has hundreds. The shape of the answer is what matters, because this is the same list that pip sees, that your program imports, and that you have to reproduce on another computer.
Where should you record your dependencies?
Two files are common, and they answer different questions. requirements.txt is a flat list of the packages to install, usually pinned to exact versions. pyproject.toml describes the project itself, with its name, version, metadata, and dependencies, and it is the file that modern tooling reads.
[project]
name = "tutorsbot-report"
version = "0.3.0"
requires-python = ">=3.12"
dependencies = [
"requests>=2.32",
"rich>=13.9",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0",
"ruff>=0.6",
]
[project.scripts]
report = "tutorsbot_report.cli:main"
Declare only your direct dependencies. If your code imports requests, list requests. The packages that requests needs in turn are the resolver's business and not yours. Listing them yourself is how a project ends up with three incompatible versions of the same library pinned inside the same file.
Version specifiers carry meaning that is worth knowing. requests>=2.32 allows any 2.x release from 2.32 upwards, which keeps security patches flowing in. requests==2.32.3 freezes one exact release, which is what a lock file does. requests~=2.32.0 means "2.32.x but not 2.33", which is the right choice when a major component moves but the minor ones do not. Spelling out a range that you do not understand is how a build starts failing six months later for reasons that nobody can reconstruct.
Requirements files still earn their place for deployment and for freezing an environment that currently works.
# Record the exact set that is currently working.
python -m pip freeze > requirements.lock.txt
# List only the packages that you asked for, without their dependencies.
python -m pip list --not-required --format=freeze
# Install from a lock file.
python -m pip install -r requirements.lock.txt
pip freeze lists everything that is installed, including the dependencies of dependencies. That is exactly what you want in a lock file, and exactly what you do not want in a hand-written requirements file. The --not-required flag gives you the top-level list instead.
How do you check an environment for broken dependencies?
Two questions come up constantly. Is anything missing, and does anything conflict? pip can answer both of them.
import subprocess
import sys
result = subprocess.run(
[sys.executable, '-m', 'pip', 'check'],
capture_output=True,
text=True,
)
print('pip check exit code:', result.returncode)
print(result.stdout.strip() or result.stderr.strip())
An exit code of zero together with the message No broken requirements found. means that every installed package has its dependencies satisfied. Anything else, and pip check exits with a non-zero code, prints the conflicting requirement for you. You fix that by reinstalling one of the two packages rather than by reinstalling everything.
For a quick look at what is really installed, the standard library can do it without pip at all.
from importlib.metadata import PackageNotFoundError, version
lines = [
'# runtime dependencies',
'pip==25.2',
'pytest>=8',
]
for raw in lines:
line = raw.strip()
if not line or line.startswith('#'):
continue
# Take the name from in front of the version marker.
name = line
for marker in ('==', '>=', '<=', '<', '>'):
if marker in line:
name = line.split(marker)[0]
break
try:
print(name, ': installed', version(name))
except PackageNotFoundError:
print(name, ': NOT installed')
Blank lines and comments are skipped, and any requirement that is missing is reported instead of crashing the script. On the machine that this was written on, the output was pip : installed 25.2 and pytest : installed 9.1.1. On yours the second line may well say NOT installed, and that is exactly the kind of drift that this check exists to catch.
What to remember
The most useful habit in this whole area is being able to throw the environment away and rebuild it. Delete the .venv folder, recreate it, install from your lock file, and run your tests. If that works, then the project is reproducible on any machine. If it does not work, you have just found the missing piece of your setup, and it is almost always a library that somebody installed by hand and never wrote down. Add the environment folder to .gitignore so that nobody commits it, and commit the requirements file so that everybody can rebuild it.
- One virtual environment per project, created with
python -m venv .venv. - Install with
python -m pipso that the installer and the interpreter always match. - Record your direct dependencies in
pyproject.toml, and keeprequirements.lock.txtfor reproducible installs. - Use
pip freezefor a full lock file andpip list --not-requiredfor the top-level list. - Run
pip checkwhen an import suddenly fails, because it names the conflict instead of leaving you to guess.
Try it yourself: In a new folder, run python -m venv .venv and activate it. Install one small package with python -m pip install. Write a two-line requirements.txt that pins it, and then run the audit snippet above against that file. Break the environment on purpose by installing a package with a conflicting version, run python -m pip check, read the message that it prints, and repair it. Then confirm that the audit snippet reports every requirement as installed again.