You're probably using uv wrong (opens in new tab)

I teach Python professionally, and constantly get questions from my students about how they should be using uv, and how to integrate it with pip, pyenv, venvs, and the like.

When I shared this post with them, my students said that it clarified things they didn't previously understand, even after reading the documentation. Part of the problem is that the documentation describes lots of options, rather than explicitly encouraging one particular path and model.

So I don't think it's just me; people are excited about uv, but aren't quite sure how to use it. But hey, I could be wrong!

As for your comment about venvs -- I teach them, I demonstrate them, and I use them when I work on programming projects.

I mostly create one-off Jupyter notebooks, which don't (in my opinion) merit their own venvs, because I don't care about locking versions. That said, I'm switching everything such that every class I teach will have not only a GitHub repo, but also a uv project, and thus an implicit venv behind the scenes. I still don't have to worry about package conflicts, but I want to be more in line with community conventions.

I dunno, every single conference I've attended over the years had at least one talk trying to make sense of packaging -- downloading, installing, venvs, creating wheelfiles, and distributing to PyPI. It was nice to say that you could choose your own tools, but it was a huge, confusing, daunting mess for many people.

I had some thoughts about how things could improve, but the core developers said that anyone with their own ideas had better think through all of the implications, because packaging is super hairy.

The uv folks basically took that as a challenge, and said, "What if we have one package manager that replaces literally everything else in the packaging ecosystem, hiding the stuff that people find confusing or annoying?" Color me impressed; they really did it.

I'm going to be honest: uv made sense to me because I already knew poetry and it was mostly a glance at the intro and then searching to figure out how to do XYZ that I already knew how to do. I can't really say learning about uv workspaces make any freaking sense to me from to docs. I don't think it's unfair to consider uv's documentation to be reference material rather than learning tools.

Now, I'm not saying I learned anything from the article (I gave up when it was talking about "uv pip" which I have never ever used and have no real idea why anyone would ever use, but that's okay). I don't think the article is a good fit for the HN python audience, and that's also okay. But I don't doubt many people can find value in it. "uv pip" exists even though I have never used it so clearly someone must be using it. I haven't used pip in years so it's not a reference point I am starting from. People do use pip and that's okay. Those people didn't suffer through figuring out poetry etc.

I do suspect that people who do system install of packages want uv workspaces. I think I want to migrate to that for my less engineered one-off jupyter calculations stuff since so far the things I've managed to get working for that sort of project have been either monorepos (which have their own issues) or millions of venvs (which constantly sync and take up space). But again I've tried to read and figure out that uv workspaces workflow and I give up after an hour or so of not figuring it out. So that's just to say I have learned to only go to astral's docs as references and even then they are incomplete (I had to guess a bit how to add a git repo via ssh as a dependency)

Sorry to disappoint! I can tell you that many people I've met, including those who have read the documentation, kept asking questions about how to use uv. This article is a summary that I came up with, based on my experience and theirs.

System-wide package installs are a weird quirk of my own work, since I'm doing very little product development and lots of one-off classes. I'm not at all recommending that "normal" developers do this, and I make sure to say that in all of the courses I teach.