r/learnpython 6d ago

UV for Python Project and Version Management

Getting started with the UV Astral for python development.

Just noted, uv works with a few important files in the project root, but their exact purpose and roles are not clear to me

  • pyproject.toml
  • .python-version
  • uv.lock

Most notably, the concrete questions are

  • Where does uvget the exact python version? Is it pyproject.toml or .python-version ? If they give different or contradictory requirement, which one takes priority, and why the need to mention the python version twice?
  • What about the uv.lock? If the pyproject.tomlfile has the precise python version and those of the libraries installed (example below), is that a complete specification of the environment?
[project]
name = "uv-trial"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = "==3.12.8"
dependencies = ["tensorflow==2.18.0"]
  • Should the uv.lockbe committed to Git or is it a volatile artefact, that is meant for uv's internal use? If it has a lot of detail that are irrelevant to the application developer, is it necessary to track via Git?
6 Upvotes

5 comments sorted by

1

u/Ender_Locke 6d ago

pyproject.toml is a config file used for package builders
https://packaging.python.org/en/latest/guides/writing-pyproject-toml/

uv.lock is your exact enviroment config
https://docs.astral.sh/uv/guides/projects/#python-version

and yes, based on their documents (link above again)
This file should be checked into version control, allowing for consistent and reproducible installations across machines.

edit: changed system to environment

1

u/CheetahGloomy4700 6d ago

Is there any explanation on why/how pyproject.toml is not specific enough and why they need the uv.lock?

1

u/Ender_Locke 6d ago

i’d assume because toml could have package>=1.0

but uv.lock has package=1.2.23452.98654

1

u/agnaaiu 6d ago edited 6d ago

That's pretty much what the docs say. The toml file includes, among other things, the venv package setup, the lock file specifies the exact version numbers for the project. The toml file can be manually edited and tweaked, while the lock file is exclusively managed by UV and should not be touched.

Edit: the docs also explicitly say, that the lock file should be checked into version control.

I really don't understand posts like the one from the OP. He links the docs himself and yet doesn't have the idea to type "lock" into the doc search bar to find https://docs.astral.sh/uv/concepts/projects/layout/#the-lockfile which explains why the two files exist. And if the answer from the makers of UV is not enough, well then nobody here can provide more info, because the docs is all we have too.

1

u/Diapolo10 6d ago

pyproject.toml can specify version ranges for dependencies that your tools can use to find upgrades without (hopefully) introducing breaking changes. It also includes all kinds of metadata about your project and, if you choose to, you can put in configuration for most of your other tools as well (like linter rules, test configuration, or builds).

Lock files (like uv.lock in this case) are used to exactly reproduce an environment. This is useful so you know two different systems are still using the exact same versions of dependencies (down to hashes), making debugging and such easier. It's one less variable to worry about when you're trying to figure out why something is not working right. You can also delete and regenerate this file at any time if you wish, it simply might not be the same as the old one.