Virtual environments, pip, and packaging basics

By default, pip install places a package into Python's global site-packages directory — shared across every script and project run with that same Python installation. Two projects needing different, incompatible versions of the same library is a genuinely common real situation, and a single global install can't satisfy both simultaneously — installing one project's required version silently breaks the other project's requirement, without any error at the moment of installation.

python -m venv .venv creates a self-contained directory with its own Python interpreter (really a lightweight reference to the real one) and its own, empty site-packages — activating it changes the current shell's python/pip commands to point at this isolated environment instead of the global installation, so anything installed afterward is scoped to just this project. This is the direct, structural fix for the version-conflict problem: each project gets its own environment, and two projects' virtual environments can hold two completely different versions of the same package without any conflict at all.

requirements.txt is a plain text manifest of a project's dependencies, and pip freeze generates it from whatever's actually installed in the current (activated) environment — pinning exact versions (==2.31.0, not a loose range) is the common convention specifically because it makes installs reproducible: anyone running pip install -r requirements.txt gets the identical set of package versions the original environment had, the same reproducibility goal this platform's Node.js domain covered for package-lock.json, just achieved through a plain committed text file instead of an automatically-generated lockfile.

pyproject.toml is the modern, standardized manifest format (defined by real Python packaging specs, not tool-specific) for a project's metadata, dependencies, and build configuration — covering more than requirements.txt's plain dependency list, including the project's own name/version (needed if the project itself will be packaged and distributed) and separate optional dependency groups (like dev, for tools only needed during development, mirroring the dependencies/devDependencies split this platform's Node.js domain covered for package.json). Modern Python tooling (pip, poetry, uv) increasingly reads this file as the primary source of truth, with requirements.txt remaining common for simpler projects or as a generated/exported artifact.

Forgetting to activate a project's virtual environment before running pip install (installing into the global environment or a different project's environment by accident) is a genuinely common, real source of "I installed it, but Python still says it's not found" confusion — the fix is always checking which environment is actually active (which python on macOS/Linux, or checking the shell prompt, which most virtual environment activation scripts prefix) before assuming an install went where it was intended to.