Fun with uv and PEP 723

Between yesterday's thread and this thread I decided to finally give uv a shot today - I'm impressed, both by the speed and how easy it is to manage dependencies for a project.

I think their docs could use a little bit of work, especially there should be a defined path to switch from a requirements.txt based workflow to uv. Also I felt like it's a little confusing how to define a python version for a specific project (it's defined in both .python-version and pyproject.toml)

I have never researched this, but I thought the .python-version file only exists to benefit other tools which may not have a full TOML parser.

> there should be a defined path to switch from a requirements.txt based workflow to uv

Try `uvx migrate-to-uv` (see https://pypi.org/project/migrate-to-uv/)

I write an ebook on Python Developer tooling. I've attempted to address some of the weaknesses in the official documentation.

How to migrate from requirements.txt: https://pydevtools.com/handbook/how-to/migrate-requirements.... How to change the Python version of a uv project: https://pydevtools.com/handbook/how-to/how-to-change-the-pyt...

Let me know if there are other topics I can hit that would be helpful!

> it's defined in both .python-version and pyproject.toml

The `requires-version` field in `pyproject.toml` defines a range of compatible versions, while `.python-version` defines the specific version you want to use for development. If you create a new project with uv init, they'll look similar (>=3.13 and 3.13 today), but over time `requires-version` usually lags behind `.python-version` and defines the minimum supported Python version for the project. `requires-version` also winds up in your package metadata and can affect your callers' dependency resolution, for example if your published v1 supports Python 3.[old] but your v2 does not.

This would’ve been really handy for me a few weeks ago when I ended up working this out for myself (not a huge job, but more effort than reading your documentation would’ve been). While I can’t think of anything missing off the top of my head, I do think a PR to uv to update the official docs would help a lot of folk!

Actually, I’ve thought of something! Migrating from poetry! It’s something I’ve been meaning to look at automating for a while now (I really don’t like poetry).

> how to define a python version for a specific project (it's defined in both .python-version and pyproject.toml)

pyproject.toml is about allowing other developers, and end users, to use your code. When you share your code by packaging it for PyPI, a build backend (uv is not one, but they seem to be working on providing one - see https://github.com/astral-sh/uv/issues/3957 ) creates a distributable package, and pyproject.toml specifies what environment the user needs to have set up (dependencies and python version). It has nothing to do with uv in itself, and is an interoperable Python ecosystem standard. A range of versions is specified here, because other people should be able to use your code on multiple Python versions.

The .python-version file is used to tell uv specifically (i.e. nobody else) specifically (i.e., exact version) what to do when setting up your development environment.

(It's perfectly possible, of course, to just use an already-set-up environment.)

Read-only TOML support is in the standard library since Python 3.11, though. And it's based on an easily obtained third-party package (https://pypi.org/project/tomli/).

(If you want to write TOML, or do other advanced things such as preserving comments and exact structure from the original file, you'll want tomlkit instead. Note that it's much less performant.)

Same, although I think it doesn't support my idiosyncratic workflow. I have the same files sync'd (via dropbox at the moment) on all my computers, macos and windows and wsl alike, and I just treat every computer likes it's the same computer. I thought this might be a recipe for disaster when I started doing it years ago but I have never had problems.

Some stuff like npm or dotnet do need an npm update / dotnet restore when I switch platforms. At first attempt uv seems like it just doesn't really like this and takes a fair bit of work to clean it up when switching platforms, while using venvs was fine.

This is a great resource, thank you for putting this together

This is wonderful. When I was learning I found the documentation inadequate and gpt4 ran in circles as I did not know what to ask (I did not realize “how do I use uv instead of conda/pip?” was a fundamentally flawed question).

You don't have to pip install it before calling uvx, do you?

You should probably look to have the uv managed venvs completely excluded from being synced, and forcing every machine to build its own venv. Given how fast and consistent uv is, there’s no real reason to share the actual venvs between machines anymore.

I agree the docs are not there yet. There is a lot of documentation but it's a description of all the possible options that are available (which is a lot). But it doesn't really tell me how to actually _use_ it for a certain type of workflow, or does a mediocre job at best.

Thank you! I wrap all my tools in very simple shell+batch scripts anyway so just specifying a different venv for each does the trick.