Strict Dependency Pinning in Python Libraries: Why == Hurts Your Users

Simon Willison's datasette-export-database plugin version 0.3a2, released 25 June 2026, carried what its author called an "embarrassingly tiny" fix: a single character change in pyproject.toml, replacing datasette==1.0a27 with datasette>=1.0a27. That one character made the plugin installable alongside every post-1.0a27 Datasette release instead of only one specific alpha build. It is a small fix, but the mistake it corrects is endemic across the Python ecosystem — and it carries a supply-chain dimension worth spelling out.

Application Pinning vs. Library Pinning

The distinction between an *application* and a *library* governs how dependencies should be specified. Applications — a deployed service, a CI pipeline script, a containerised workload — should pin exactly, typically via a lock file (pip freeze, poetry.lock, uv.lock). Exact pins reproduce the environment reliably and catch supply-chain substitution attacks at the boundary where code actually runs.

Libraries and plugins are different. When a package published to PyPI hard-pins a dependency with ==, every project that installs it inherits that constraint. If two installed packages demand different exact versions of the same dependency, pip raises a conflict and the install fails. The result is silent incompatibility that surfaces only when a user attempts pip install — often during a production deployment or a CI run.

The Supply-Chain Risk in Strict Alpha Pins

The datasette case involved an alpha release (1.0a27). Alpha versions are, by definition, pre-stability: they may contain unfixed security defects, and they typically do not receive backported patches after a newer alpha ships. A library that hard-pins to an alpha locks every downstream user to that snapshot. If a vulnerability is later found in datasette==1.0a27 and fixed in 1.0a28, the plugin's constraint prevents the fix from propagating — a classic supply-chain pinning trap.

The same pattern is well-documented in the npm ecosystem: a transitive dependency pinned to a version with a known CVE causes automated scanners to flag the issue, but the fix cannot propagate because an upstream library refuses to widen its range. Security teams then face the choice of patching the transitive package out-of-band, maintaining a private fork, or waiting indefinitely for the upstream author to act.

Best Practices for Library Maintainers

• Use a lower-bound pin (>=1.0a27) to declare the minimum tested API, not an exact lock.
• Add an upper-bound exclusion (<2.0) only when you have evidence of a confirmed breaking change — not as a precaution.
• Run your test suite against the latest released version of every dependency in CI to detect breakage before it reaches users.
• Use pip-audit or osv-scanner in CI to surface known vulnerabilities within your declared dependency range.
• Document every dependency-range change in your changelog so downstream consumers understand the impact.

What This Means for Security Teams

If your organisation consumes open-source Python packages, the dependency range policies of your third-party libraries are part of your software supply-chain attack surface. Tools such as pip-audit, Dependabot, and OSV-Scanner should be configured to flag libraries that hard-pin transitive dependencies to outdated or pre-release versions. A library maintainer's one-character oversight — == instead of >= — can silently prevent a security patch from reaching your production environment without any error or warning.