Python Dependency Management

dependencies = ["httpx>=0.27"] in pyproject.toml expresses a genuine intent — 'any version 0.27 or newer is acceptable' — but it is deliberately *not* a pin to one exact version. This flexibility is useful at the declaration level: it lets your package remain installable alongside other packages that might require a slightly different but still-compatible version of the same dependency, rather than forcing an exact-version conflict.

The cost of that flexibility is that dependency *resolution* — the actual process of picking one specific version that satisfies every constraint across your entire dependency graph — can legitimately produce a different result at different points in time, purely because new compatible releases keep being published. Installing your project today might resolve httpx to 0.27.0; installing the exact same pyproject.toml, unchanged, three weeks later might resolve it to 0.27.2, simply because that newer, still-compatible version now exists and the resolver has no reason to prefer the older one.

This is the direct cause of a large fraction of 'works on my machine' bugs: two developers, or a developer's laptop versus CI, running pip install against the exact same declared ranges at different times, ending up with a subtly different resolved dependency tree — and one of those trees happens to trigger a bug the other doesn't.

Your project's *direct* dependencies — the ones you actually wrote in [project.dependencies] — are typically a short, manageable list. But each of those dependencies has its own dependencies (httpx depends on httpcore, which depends on h11, and so on), and each of *those* is typically declared as a range too. The full resolved dependency tree for even a modest project routinely includes dozens of transitive packages you never directly named and may never have heard of.

A resolver's job is to find one specific version for every package in that entire tree that simultaneously satisfies every constraint from every other package that depends on it — a genuinely hard constraint-satisfaction problem, which is why modern resolvers (uv, poetry, pip's newer resolver) can take real, sometimes noticeable time on a large dependency graph, and why two different resolver runs, even with identical inputs, could theoretically make different valid choices when multiple versions satisfy all constraints equally.

This is precisely why relying on 'just run pip install from pyproject.toml every time' does not give you reproducibility: you're asking the resolver to redo this entire constraint-satisfaction process fresh, against a set of available package versions that keeps growing on PyPI over time, every single time you install.

A lock file (uv.lock, poetry.lock, or a pip-compiled requirements.txt with pinned versions) is the *output* of running dependency resolution once, recorded exactly: every package in the full tree, direct and transitive, pinned to one specific version, typically alongside a cryptographic hash of the exact package artifact. It is not something you write by hand — it's generated by your dependency-management tool from your declared ranges, and then committed to version control alongside pyproject.toml.

The critical workflow change this enables: instead of pip install . (which re-resolves from ranges every time), you run an install command that reads *from the lock file* — uv sync, or pip install -r requirements.lock.txt with pinned pip-compile output — which skips resolution entirely and installs exactly the versions the lock file specifies. Two machines, two points in time, running that same lock-file-based install command, get byte-for-byte identical dependency trees, hashes and all.

The hash verification specifically defends against a subtler risk than version drift: it guarantees the *exact bytes* of each installed package match what was originally resolved and tested, protecting against a compromised or tampered package artifact being silently substituted — a real supply-chain security consideration, not just a reproducibility one. The professional workflow is: declare ranges in pyproject.toml for flexibility, regenerate the lock file deliberately when you want to pick up updates, and always install from the lock file everywhere else — local dev, CI, and production.

"Works on my machine" is almost always a dependency-locking problem wearing a different name. Let's fix that permanently.

A version RANGE like httpx>=0.27 is a constraint, not an exact version. Two installs weeks apart can resolve to different actual versions.

Checkpoint: Does httpx>=0.27 in pyproject.toml guarantee the exact same version is installed every time?

• →No — it only guarantees a version satisfying that range, which can differ across installs over time
• →Yes — >= always resolves to the exact same version once written

Transitive dependencies compound this: httpx itself depends on other packages, each with their own ranges — the resolved tree can shift even more.

A lock file pins the EXACT resolved version (and hash) of every package in the tree, direct and transitive — reproducible, byte for byte.

Installing FROM a lock file (not just from pyproject.toml directly) is what makes two machines end up byte-for-byte identical.

Checkpoint: Why install from a lock file rather than directly from the version ranges in pyproject.toml for reproducible environments?

• →A lock file pins exact versions (and hashes) for the entire dependency tree, guaranteeing identical installs
• →Installing from a lock file is always significantly faster, which is the main reason

With dependencies declared and locked reproducibly, virtual environments are the last piece — isolating this project's dependencies from every other project on the same machine.

Reproduce a Real Non-Reproducible Install. Finish resolve_at_time(): the same range constraint can resolve differently at different points in time.