{"id":627,"date":"2026-08-29T05:04:57","date_gmt":"2026-08-29T05:04:57","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/python-dependency-management-the-import-you-never-declared\/"},"modified":"2026-08-29T05:04:57","modified_gmt":"2026-08-29T05:04:57","slug":"python-dependency-management-the-import-you-never-declared","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/python-dependency-management-the-import-you-never-declared\/","title":{"rendered":"Python Dependency Management: The Import You Never Declared"},"content":{"rendered":"

I read Simon Willison’s release notes the way other people read box scores, and last week a two-line postmortem in one of them sent me on a Saturday audit of every pyproject.toml I own. The short version: fresh installs of his llm<\/code> CLI broke overnight, through no change of his own, because a library he imported directly was only being installed as a side effect of a different dependency. Then that dependency stopped needing it, and the floor disappeared.<\/p>\n

I found the same landmine in two of my own projects within the hour. Odds are decent it’s sitting in one of yours, which is why this post is about python dependency management and the single rule that would have prevented the whole mess.<\/p>\n

What actually broke<\/h2>\n

The sequence, from Simon’s 0.32.1 release note<\/a>: the OpenAI Python library dropped its usage of httpx. llm<\/code> imports httpx in its own code, but never declared it; the package arrived as a transitive dependency of openai<\/code>. When openai 3.0 stopped depending on it, every fresh pip install llm<\/code> produced a tool that crashed on import. Existing installs kept working, which is the cruel part. Nothing looked wrong on any machine that already had the package.<\/p>\n

The immediate fix was pinning openai<3<\/code>. The proper fix landed in llm 0.33<\/a>, which switched to the new httpx2 library alongside the ecosystem. Anthropic’s SDK made the same migration in its 1.0 release, and plugin authors got to update all over again.<\/p>\n

None of this is a criticism of Simon, to be clear. He diagnosed and shipped a fix within a day, in public, with his reasoning attached. That transparency is exactly why the bug is useful to the rest of us: it’s a clean specimen of a failure mode that usually stays murky.<\/p>\n

Why nobody’s tests caught it<\/h2>\n

The nastiest property of this bug is that it’s invisible everywhere except a clean machine. Your laptop has the package because it’s been installed since forever. CI probably has it too, because dependency caches exist precisely to avoid reinstalling from scratch, and a cache that predates the upstream change will keep serving the old dependency tree indefinitely. The test suite imports httpx, finds it, and goes green. Everything agrees the project is fine, and everything is wrong.<\/p>\n

The only environment that tells the truth is a fresh install from your declared dependencies, resolved today. That’s what new users get, which is why they hit the crash while maintainers see nothing. If your CI never does a cold, cacheless install of your published package, you’re testing the environment you accumulated, not the one you ship. I now keep one job that does exactly that: build the wheel, install it into an empty venv with no cache, import the entry point. It’s slow. It’s also the only job that would have caught this.<\/p>\n

The rule: declare what you import<\/h2>\n

If your code contains import httpx<\/code>, then httpx belongs in your dependency list. Full stop. It doesn’t matter that some other package already brings it in. Your dependencies’ dependencies are their implementation details, and they can change in any release, including a patch release, without notice and without it being anyone’s fault.<\/p>\n

I got this wrong for years, and I got it wrong for a reason that felt responsible at the time: I didn’t want to duplicate entries. If openai<\/code> needs httpx anyway, declaring it twice seemed redundant, and a shorter dependency list felt cleaner. But “redundant” was doing a lot of work in that sentence. The declaration isn’t redundant; it’s the only thing that makes your actual requirements visible to the resolver. Without it, your install works by coincidence.<\/p>\n

The test I use now: could I delete any single line from my dependency list, reinstall from scratch, and still import everything my code imports? If deleting a line breaks an import that line doesn’t mention, something is undeclared somewhere.<\/p>\n

Before and after<\/h2>\n

Here’s the shape of the bug in a pyproject.toml:<\/p>\n

# Before: httpx arrives by accident, as a side effect of openai\n[project]\nname = "my-tool"\ndependencies = [\n    "openai>=2.0",\n]\n<\/code><\/pre>\n
# my_tool\/client.py\nimport httpx  # works today, undeclared, one upstream release from breaking\n<\/code><\/pre>\n
# After: everything the code imports at runtime is declared\n[project]\nname = "my-tool"\ndependencies = [\n    "openai>=2.0,<3",\n    "httpx>=0.27",\n]\n<\/code><\/pre>\n
That’s the entire fix. It’s almost insultingly small, which is exactly why it never gets prioritized until a Friday deploy fails.<\/p>\n
A close cousin of the same bug lives in optional extras. If you declare a package under [project.optional-dependencies]<\/code> but import it unconditionally at module load, everyone who installs without that extra gets the same crash on import. Either guard the import or promote the dependency to the main list. I’ve shipped that one too, and the bug report politely asking why my “optional” feature was mandatory still stings a little.<\/p>\n
Finding your undeclared imports<\/h2>\n
You don’t have to eyeball this. deptry<\/a> scans a project and reports exactly this class of problem, including imports that resolve only through transitive packages:<\/p>\n
pip install deptry\ndeptry .\n<\/code><\/pre>\n
It flags missing dependencies, unused declared dependencies, and transitive imports in one pass. On the first project I pointed it at, it found the httpx pattern twice and a requests import I’d been getting from an SDK I was in the middle of removing. Ten minutes, three real bugs.<\/p>\n
For the inverse question, “what is pulling this package in?”, pipdeptree does the job:<\/p>\n
pip install pipdeptree\npipdeptree --reverse --packages httpx\n<\/code><\/pre>\n
Run that before you assume anything about where a package comes from. The answers surprise me about a third of the time, and I do this for a living.<\/p>\n
Pinning is not the same thing as declaring<\/h2>\n
One confusion worth clearing up, because I see it in code review constantly: a lockfile does not solve this. A lockfile freezes the exact versions of whatever the resolver happened to select, including your accidental transitive deps. Your app installs reproducibly right up until you regenerate the lock, and then the floor can vanish just like it did for llm<\/code>. Locking preserves a coincidence; declaring removes it.<\/p>\n
Version caps are the other half, and they’re contested territory. The packaging community has argued for years about blanket upper bounds, with good reason: over-capping causes its own resolution misery downstream. My personal rule is narrower. I cap the major version of SDKs with a track record of breaking me, the way openai<3<\/code> saved llm’s users, and I leave stable libraries uncapped. The dependency specifiers guide on packaging.python.org<\/a> covers the syntax; the judgment about which packages deserve caps is yours, and it comes from scar tissue.<\/p>\n
There’s an extra reason I care about this lately: AI-generated code makes the undeclared-import problem worse. An agent writing Python will cheerfully import whatever happens to be importable in its environment, with zero awareness of what’s declared. I already sandbox the Python that agents write<\/a> before running it; deptry in CI is the packaging-side complement, catching what the agent assumed but never declared. Most of the automation pipelines I build for clients<\/a> now have both wired in from day one.<\/p>\n
The ten minute audit<\/h2>\n
Here’s the thing to do this week, on one repo, the one that would page you if installs broke:<\/p>\n
pip install deptry\ndeptry . || true          # see everything it flags\npipdeptree --warn fail    # surface version conflicts while you're here\n<\/code><\/pre>\n
Fix what deptry reports: add the missing declarations, delete the unused ones. Then regenerate your lockfile from the corrected list and run the test suite. If everything passes, you’ve converted a pile of coincidences into an actual specification of what your project needs, and the next time a big SDK sheds a dependency over a weekend, you’ll read the postmortem the way I read Simon’s: with sympathy, and with coffee, and with nothing to fix.<\/p>\n","protected":false},"excerpt":{"rendered":"
A transitive dependency broke fresh installs of a popular Python CLI overnight. What that failure taught me about python dependency management done properly.<\/p>\n","protected":false},"author":2,"featured_media":626,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"A transitive dependency broke fresh installs of a popular Python CLI overnight. What that failure taught me about python dependency management done properly.","rank_math_focus_keyword":"python dependency management","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[147,528],"tags":[686,688,687,685,530],"class_list":["post-627","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-backend","category-python","tag-dependencies","tag-deptry","tag-packaging","tag-pip","tag-python"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/627","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=627"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/627\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/626"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=627"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=627"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=627"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}