Environments and Dependencies

A bare pip is a script on PATH whose shebang points at whichever interpreter installed it, so PATH order decides where the install lands. python -m pip runs the pip belonging to the interpreter you just named, so the packages land where that interpreter imports from.

pyproject.toml declares abstract dependencies: the ranges a package can work with, re-resolved at install time. A pinned requirements.txt records one concrete resolution so a particular deployment installs exactly the same versions every time.

Besides a name from an index, pip install accepts a path to a project directory, wheel or sdist, a direct URL, a version-control reference such as git+https at a tag or commit, and -r to read requirement lines from a file.

It owns the project end to end: it creates and syncs a project-local virtual environment, resolves the declared dependencies into a lock file, and runs commands inside that environment. pip and venv each do one piece and leave the wiring to you.

Activation is shell bookkeeping only. Sourcing the activate script prepends the environment's bin directory to PATH, exports VIRTUAL_ENV, unsets PYTHONHOME and marks the prompt. Calling .venv/bin/python directly uses the same environment with no activation at all.

pip freeze prints a flat list of whatever is installed in one environment: names and exact versions only. It carries no artefact hashes, no environment markers and no dependency graph, so it cannot reproduce a resolution elsewhere.

PEP 621 defines a tool-agnostic project table in pyproject.toml holding a project's core metadata: name, version, description, requires-python, abstract dependencies, extras and entry points. Every build backend and project manager reads that same table instead of its own bespoke format.

pip's resolver tries the newest candidate for each requirement and, on a conflict, backs up to older ones. Every candidate costs a metadata fetch, and a source distribution costs a build, so a wide unbounded search runs for minutes. Narrow the ranges.

Installed code lands in one flat site-packages directory, and an import binds a name to exactly one module, so two versions of the same distribution cannot coexist. An installer must therefore find one version that satisfies every requirement at once.

Anything that is not module source read at import time: project metadata such as the version, dependencies and console-script entry points, compiled extension modules, and — under a strict editable mapping — newly added modules. Editing existing Python source needs nothing.

Metadata plus a redirection, not your code: a normal .dist-info directory, and a .pth file whose line either adds your source directory to sys.path or imports a small generated finder that maps declared packages to their files.

When an executable file starts with #!, the kernel runs the interpreter named on that line and passes the script as an argument. #!/usr/bin/python3 pins one absolute interpreter; #!/usr/bin/env python3 defers the choice to a PATH lookup.

--no-deps installs only the distributions you named and ignores the requirements declared in their metadata, so pip does no resolution and installs nothing extra. It is right when something else has already produced the complete, exact set to install.

pip keeps a per-user cache of downloaded files and index responses, plus wheels it built from source distributions, so a repeat install skips the download and the rebuild. --no-cache-dir disables it, keeping an image layer small but repeating that work.

Use extras for optional features your consumers install; use PEP 735 dependency groups for requirements only the repository needs, such as test, lint and docs tooling. Groups are local and never appear in the published distribution's metadata, so they cannot be installed by a consumer.

Read the block headed "The conflict is caused by": each line names a requester and the range it demands. Lines saying the user requested something are your own direct requirements; the rest are transitive. Those ranges share no version.

At startup the interpreter resolves the path of its own executable and looks for a pyvenv.cfg file beside its directory. Finding one, it sets sys.prefix to the environment, records the original installation in sys.base_prefix, and uses the environment's site-packages.

Stop guessing and ask the import system: print the module's file or importlib.util.find_spec(name).origin in the exact interpreter that runs the code, then compare it against sys.path order and sys.executable to see which copy wins.

That interpreter is managed by the operating system's own package manager, which marks it with a file declaring it externally managed. pip honours the marker and refuses to modify it. The fix is to install into a virtual environment you own, not to force the install.

It makes pip reject any downloaded artefact whose hash is not listed in the requirements file. It also forces every requirement, transitive ones included, to be pinned with == and carry at least one hash, so nothing unlisted can install.

--index-url replaces the default index; --extra-index-url adds a second index that is searched alongside it. pip pools candidates from every configured index and picks the best version overall, so it has no notion of one index being more trusted than another.

You now have two install paths and only one source of truth. The manager's lock file is its own format that pip cannot read, so the deployment image installs from an exported file that can silently fall behind — meaning tests and production run different dependency sets.

Work from cheapest and most reversible outwards: check whether the capping requirement is stale and a newer release of that dependency widens it, loosen your own pin, then consider dropping the dependency, vendoring it, or splitting the two consumers into separate processes.

A virtual environment is full of absolute paths pinned to the machine that built it: the home key in pyvenv.cfg, console-script shebangs, and the interpreter symlink. Ship pinned requirements and build the environment on the target instead.

Separate intent from resolution: keep ranges in project metadata, commit a resolved lock for every deployable, install from the lock rather than re-resolving, and re-resolve on a schedule so upgrades arrive as a reviewed change.

Standardize when your repositories are similar enough that one workflow fits them, and when the exit is cheap. Judge it on repository heterogeneity, CI install cost, contributor onboarding, index and authentication support, and how much of the setup survives swapping the tool out.

py is a single command that dispatches to one of several Python installations registered on the machine. It obeys an explicit version argument such as py -3.13, otherwise a script's shebang line, an active virtual environment, or its configured default — normally the newest installed Python 3.

A constraints file only bounds versions: it says that if a distribution ends up being installed, it must satisfy this specifier. It never causes an installation. A requirements file passed with -r also decides what gets installed.

It writes include-system-site-packages = true into pyvenv.cfg, appending the base installation's site-packages to sys.path after the environment's own. Use it to reuse a binary package the base interpreter already has; it costs you reproducibility and clean isolation.