Repository navigation
Feedback: "Managing Application Dependencies" and "Packaging Python Projects" Tutorials Are Incompatible #1562
Description
Hi! Thank you for writing all of this documentation so clearly, it has been extremely helpful.
"Managing Application Dependencies" suggests Pipenv. "Packaging Python Projects" defaults to hatchling. I assumed that you could follow the two tutorials, in-order, and end up with a working python project, but I had to write a shim to teach hatchling to read a Pipfile.lock. Pipenv doesn't seem to interact with pyproject.toml, and Hatch seems to only read dependencies from there.
I don't know enough about python packaging to suggest a solution. I think you should be able to follow the tutorials as-written and have them be compatible.
`Pipenv.lock` hookpyproject.toml:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.metadata.hooks.custom]
path = ".ci/dependencies.py".ci/dependencies.py:
"""Dynamically update the dependencies metadata based on the Pipfile.lock file.""" # noqa: INP001
import json
from typing import Any
from hatchling.metadata.plugin.interface import MetadataHookInterface
class PipfileLockedDependencies(MetadataHookInterface):
def update(self, metadata: dict[Any, Any]) -> None:
with open("Pipfile.lock") as f:
pipfile_lock_data = json.load(f)
metadata["dependencies"] = [
f"{pkg}{data['version']}"
for pkg, data in pipfile_lock_data["default"].items()
]I feel somewhat bad about suggesting new projects all include this, but at my organization we really want to make locking dependencies the norm. I hope I am missing something obvious.
Activity
willingc commented on Jun 19, 2024
Thanks for the feedback @rmartine-ias. You have found a legitimate discrepancy that we should address.
I think a good next action would be to determine if the Pipenv recommendation is still the best option (pip-compile and uv would be other options) to recommend in "Managing Application Dependencies".
As for working with Hatch and hatchling, their docs mention third party tools to create the lockfiles.
funkyfuture commented on Feb 26, 2026
i was also very irritated after trying to start off a project w/ pipenv which build backend i'd now set to use. but pipenv seems to expect that itself will be used to install a (n application) package.
my impression, also from the discussions at pipenv's repo, is that pipenv never caught up with the establishing of pyproject.toml and should therefore be considered as obsoleted.
imo two arguments speak against including uv in the packaging guide:
considering that the chapter is about dependency management, i think it'd be worthwhile to see which tool will provide genuine support for pylock.toml. hatch would be the obvious choice to complement the follwoing chapter, lockfile support is tracked there: pypa/hatch#749
ncoghlan commented on Mar 2, 2026
Not to detract from the general question about pipenv as the default application dependency management option, I do want to clarify the subtle nature of one assumption:
The two tutorials actually cover different tasks, so there wasn't originally an inherent assumption that they'd both be carried out in the same repository and hence benefit from using the same tooling (when we added pipenv as the default recommendation, that style of locking was still primarily oriented towards the "web application deployment" use case, rather than package development).
However, in practice, many folks publishing projects either want to treat their test suite as an application for CI execution purposes, or evolve their directly deployed application into a published package and it's in those specific cases that pipenv's age and different design assumptions work against it (creating the hard breakpoint described here, where transitioning from "application deployed with pipenv" to "Python project managed and published with ???" requires either switching tools, or building a bridge between them).
When it comes to application dependency management (and even CI dependency management) pipenv is still a viable choice, but it's definitely no longer the best default recommendation (especially for folks that aren't specifically doing web application deployment, or something that closely resembles it).
That said, aside from actually doing the work to draft an update switching to a different default recommendation, one of the key challenges has been choosing which of the alternatives mentioned in https://packaging.python.org/en/latest/tutorials/managing-dependencies/#other-tools-for-application-dependency-management to recommend instead (or deciding to go for a tabbed presentation in the examples, along the lines of that now used in the packaging tutorial).
PDM is my own personal choice and recommendation, with the distribution = false setting covering pure app deployment, while distribution = true covers the "running a test suite in CI" case. There are also other features I appreciate, like being able to opt in to using uv as the underlying resolver, and being able to pin pbs-installer separately from PDM itself to control the exact Python runtime selection if using that feature. pdm-backend is one of the non-default tabs in the packaging tutorial. It definitely has its quirks though, especially if you're trying to set up a cross platform lockfile, so while I do think it would be worthy of a tab in a tabbed presentation, I'm not sure the UX is seamless enough to make it the default recommendation for beginners.
uv is honestly a decent recommendation (and its scope is pretty comparable to that of PDM/poetry/hatch). It doesn't provide as much scope as the tools written in Python for people to look under the hood and see how it is implemented, though (since the whole thing is written in Rust). uv uses the presence or absence of the build-system table to determine if a project publishes a package or not. uv-build is one of the non-default tabs in the packaging tutorial. One of uv's strongest features is that as a standalone executable with the ability to download and install Python runtimes, it offers some interesting options for bootstrapping user level Python installations. Definitely worthy of a tab in a tabbed presentation, and arguably worthy of being presented as the default option simply from a UX quality perspective (especially their implementation of cross platform lockfile generation).
While hatch works for the "running a test suite in CI" dependency management use case, as far as I am aware (and can determine by looking at its documentation) it doesn't have an "application deployment" mode for cases where the project itself is not a package. hatchling is the default tab in the packaging tutorial. (It seems worth noting that hatch is also the only candidate project that's directly under the PyPA umbrella, although the weight I think we should give that over the technical detail of supporting app-only deployments when considering the default recommendation is limited. I'd have no concerns with giving it a non-default tab in a tabbed presentation, though).
poetry doesn't have a tab in the packaging tutorial, at least in part due to its notational quirks (some of which are due to design decisions predating standardised notation, but others just being a matter of the authors not liking the standard notation which provide optional shorthand notations for some comparisons which need separate upper & lower bounds in the standard notation). It has a genuine niche as a tool folks may opt to use because they like the design choices it makes, but I don't consider it a good candidate for a default recommendation~~, or even for a non-default tab in a tabbed presentation~~. Still a valuable link for an "Other alternatives to consider" section like the current one, though.
pip-tools (or uv pip) are great options for advanced build-your-own-workflow use cases, but also aren't good options to cover in detail in a tutorial. micropipenv is similarly a niche tool for specific use cases that is worth linking to, but not covering the specifics of.
(edit: amended some inaccurate comments about poetry, and changed my mind on it being a suitable candidate for a non-default tutorial tab)
sinoroc commented on Mar 2, 2026
I am not sure this is still the case, though... Of course, I do not know for sure what you are referring to, but it feels like you might be referring to [tool.poetry] vs. [project]. If that is the case, then as far as I know, Poetry has had support for the [project] notation and even [dependency-groups] for quite a while now, it is even the default. I have not followed closely, but my impression is that Poetry has now caught up with all the (significant) PyPA standardized specifications.
ncoghlan commented on Mar 6, 2026
Aye, the poetry devs are good about ensuring the features they offer are a strict superset of the standardised ones. That isn't my concern from a tutorial perspective.
The challenge from a tutorial perspective is the extra parts in https://python-poetry.org/docs/dependency-specification/ (caret bounds, tilde bounds, at bounds that aren't direct URLs).
After rechecking the details, I'll withdraw my objection to a non-default tab in either tutorial though, as if you're sticking to the standard fields and syntax, it works the same way any of the others do.
docs: explain Pipenv application lockfiles versus package metadata (p…
docs(tutorial): clarify Pipenv and packaging tutorial boundaries (pyp…
rgommers commented on Nov 13, 2026
I'm consolidating #1060 into this issue, since both are about improving the current "Managing Application Dependencies" tutorial and its relationship to the packaging tutorial. While #1060 is older, this issue has much more relevant discussion. I'll copy the full contents of that issue as is here (comment by @pradyunsg):
See #912 for full context.
The idea is to present the available dependency management tooling options as a gradient of increasing complexity + scope-of-tooling -- as done in Installing Scientific Packages -- putting things like manually managed pip requirements.txt files, pip-tools, pipenv and poetry on "equal" footing; moving away from a guided tutorial to using pipenv to being a guide on how to pick the right option for you.