uv
uv copied to clipboard
astral-sh
uv run fails if project table is missing
I often interact with repositories with python code that has a pyproject.toml for tool configuration only. Unlike https://github.com/astral-sh/uv/issues/6419, I can't really tell if this is compliant or not, but it became common when black was released. It was one of the first really popular tools that required configuration to be in pyproject.toml.
Steps to reproduce.
$ uv --version
uv 0.4.0
$ mkdir /tmp/test-pyproject
$ cd /tmp/test-pyproject
$ touch pyproject.toml
$ uv run python
error: No `project` table found in: `/tmp/test-pyproject/pyproject.toml`
I think we're unlikely to support projects with a name. It just simplifies a lot of things and enables us to have better error messages, etc. We should give a better error message here though!
Hello, I am still getting the exact same error here. This is on uv 0.5.6. The original author's reproducer still works exactly as is. The error message hasn't changed.
I think I misunderstood the initial report and fixed a slightly different case (the case wherein [project] is present but project.name is absent). I think it's correct for us to be erroring here -- is there a real use-case for this?
I'm not familiar with what a pyproject.toml is supposed to do and not to do, and I don't really care tbh. If I can't even query my python version through uv anymore just because this file is present, I think that's problematic. I'm also not sure why this file affects the uv run python [...] command in the first place: afaic this should act the same as if I did source <path to venv>/bin/activate && python [...], which doesn't care about the pyproject.toml at all.
Perhaps throwing a warning about an ill-formed pyproject.toml and then continuing normally would be better?
Whether there's a use-case for this, I don't know. I can only tell you that people seem to be using it that way, because I've already run into that error on another 2 repos since I posted that comment a couple hours ago.
I just looked at https://docs.astral.sh/uv/configuration/files/, which says:
"If a pyproject.toml file is found, uv will read configuration from the [tool.uv] table.
[...]
(If there is no such table, the pyproject.toml file will be ignored, and uv will continue searching in the directory hierarchy.)"
which is not the case at the moment.
The main intention of pyproject.toml (created long before uv was conceived) was to define a python project. It declares its name, version, author, dependencies, etc and also declare how it is built. Basically replace setup.py, setup.cfg etc. as well as be a common configuration file format for python project tools. However, just like setup.cfg, it can also store configuration for different tools that you might use in your project, like isort, black, ruff, pytest, mypy, as well as uv. @DeinAlptraum The page you are linking to only refers to uv using pyproject.toml as ONE way to configure it. I agree it is very confusing though and it should probably be rewritten to highlight that better. There is more documentation about the project specific parts of pyproject.toml starting at https://docs.astral.sh/uv/concepts/projects/layout/
Tools that store its config in pyproject.toml will only read that file for its own configuration and then ignore everything else. It might check that the file is valid toml, but that's it.
Most tools that read pyproject.toml can also read other configuration files like setup.cfg, tox.ini, their own format.
Except black. It only reads pyproject.toml. Black was adopted by many projects. Even projects that had not yet moved to using pyproject.toml for the project metadata. This means that there are a lot of pyproject.toml files out there without a [project] table. (We are likely outliers, but I found 1291 pyproject.toml files at the company where I work, of which only 374 have a [project] table).
uv is not like most tools. It has many different use cases. Since 0.4 you can run it as a project tool. You can also use it as a pip and/or pip-compile replacement.
However, what makes things everything extra confusing is that you CAN ALSO use project specific commands like run outside of a project, where there is no pyproject.toml. What seems to happen here is that a special implicit project is created on the fly.
Because that works, it is very confusing when it doesn't work if you are in a directory of a python project that has a pyproject.toml without a [project] table.
Personally I am ok if requires a project table in pyproject.toml files. I am teaching all my colleagues how to migrate to pyproject.toml files anyway. But I would also be totally ok if uv would treat a missing project table the same as a missing pyproject.toml file. I think this will make the transition to uv smoother.
There would of course have to be some corner cases that I can't figure out now. What if you find two pyproject.toml files. One in the root of a project with a [project] and another in a subdirectory without a [project]. Both files have [tool.uv...] sections. Will one [tool.uv...] section still override the other? Or can the validation rule be changed to only require a [project] table if there is also a [tool.uv...] section?
@jooon wow, thanks a lot for taking the time to explain!
I see that the docs you linked also mention that "uv requires this file" so I guess that's fair. Makes me wonder why it works even without it then, but I'm not complaining :D
Like you said, uv would at least benefit from a clearer documentation & communication of how running it with and without a project file present differs, because at the moment it's quite confusing - especially when you're not familiar with pyproject.tomls and you're just using uv to manage your venv and dependencies
But I would also be totally ok if uv would treat a missing project table the same as a missing pyproject.toml file
I would prefer this, but just improving the error message would also be sufficient to resolve this issue imo. Perhaps a link to the docs that explains how uv expects pyproject.toml to be used, or some sort of flag that could be set to ignore this error or similar.
I think this should be reopened
it's frustrating at the moment that trying to use uv with certain projects fails, e.g. if pyproject.yaml exists but only contains settings for black, which is pretty common, uv simply won't work at all unless you migrate everything over to pyproject.yaml
imo if [project] is missing from pyproject.yaml uv should behave as if pyproject.yaml doesn't exist at all.
agreed with @frankh pyproject toml only exists for pyright and black for me, I dont need any metadata :(
It would be nice to be able to use this with projects that we don't have control over and may not be precisely as expected. An example might be trying to work with a project like this (simple example, but there are tons of similar scenarios): https://github.com/rohitg00/s3-file-share-for-free
I just ran into this as a friction point on a project which is mostly not Python but has a couple of utility scripts. It had a pyproject.toml file which existed only to hold Ruff's settings (migrated from Black) so the fix ended up being renaming the file to .ruff.toml but it was an annoying bit of friction since uv run --script is otherwise so painless for single-file programs.
I think the [project] section could be made optional. Use case is running a python tool like yamllint in a non-python project, so ideally my pyproject.toml would only hold the dependency declarations, not a useless project.name or project.version because those are declared in other files.
I believe this is being addressed in https://github.com/astral-sh/uv/pull/14113
That one looks promising. Personally I only use uv run and uv sync in such projects and I think those commands are covered.
As far as I can tell the issue also creates a Catch-22 that prevents you from using uv to run tools (ini2toml, pdm) to migrate from setup.cfg to pyproject.toml.
