Repository navigation
Briefcase doesn't work with uv #2314
Description
EDIT: most definitely not a bug.
The following workflow with uv works:
➜ uv run --with briefcase briefcase new
➜ cd helloworld
➜ uv run --no-project --with briefcase briefcase dev
This (very obviously, in retrospect) doesn't work and results in an error, which I was initially confused by:
➜ uv init --no-readme
➜ uv add briefcase
➜ uv run briefcase new
➜ cd helloworld
➜ uv run briefcase dev
error: No `project` table found in: `/Users/andrewsanchez/Projects/beeware/beeware-console-app/helloworld/pyproject.toml`
Briefcase configuration error: No tool.briefcase section in pyproject.toml
Environment
- Operating System: macOS Sonoma 14.6.1
- Python version:
Python 3.12.9 - Software versions:
- Briefcase:
0.3.23
- Briefcase:
Activity
[-]docs: hello world for console app doesn't work[/-][+]Briefcase doesn't work with uv[/+]freakboy3742 commentedon May 24, 2025
At present, we don't recommend the use of uv with Briefcase. We haven't fully audited Briefcase for uv usage, and uv does enough "weird" things that it becomes problematic for some Briefcase use patterns. If you use uv and something breaks, you get to keep all the shiny pieces. :-)
In this case, the error message is an error with uv.
uv is correctly reporting that
pyproject.tomldoesn't contain a[project]section. This is correct - and by design. Apyproject.tomlfile is atomlconfiguration file. PEP 518 doesn't require the existence of a[project]table. It does define the existence of atooltable - which Briefcase uses; and PEP 517 defines the existence of a[build-system]table, which Briefcase doesn't use. PEP 621 defines the existence of a[project]table - but Briefcase doesn't require the definition of that table, primarily because it predates the existence of PEP 621.To the best of my understanding, there are no required keys in
pyproject.tomlunless you're packaging a specific application, using a specific tool - in which case, PEP 621 or other configurations may be in effect.We have a longer-term goal to migrate to using PEP 621 metadata as a canonical definition for some metadata - but until that time, this is a
uvbug.I don't know
uv, but it looks like the--no-projectoption exists to work around the fact thatpyproject.tomldoesn't contain a[project]section. I don't know why this option exists - you'd have to take that up with the maintainers ofuv.The other workaround would be to manually add a
[project]table to yourpyproject.toml. Briefcase will honor some PEP 621 keys.I'll keep this open as a known issue with uv compatibility.
andrewsanchez commentedon May 24, 2025
That all makes sense. I rushed back here to close or delete the issue after realizing these things. 😆 Thanks!
Regarding
uv run --no-projectfreakboy3742 commentedon May 25, 2025
I'm going to migrate this issue to the Briefcase repository, since it's a Briefcase-specific issue.
Shuuen-Yukibi commentedon Jan 3, 2026
[ChatGPT-generated reply]
Hi! I ran into the same uv + Briefcase workflow described in this issue and wanted to confirm whether the approach below is correct.
Why uv is required in my case
Context / problem
uv run briefcase ...triggers uv “project mode”, which expects a PEP 621[project]table inpyproject.toml.[tool.briefcase]and may not contain[project], souv runcan fail with “No project table found”.uv run --no-project --with ...) avoids uv’s project-table validation while still letting me stay in a uv-only environment.Working solution (Windows)
Create the app (from
.\beeware):cd /d .\beeware
uvx briefcase@latest new
(This generates the project folder; in my case it’s .\beeware\Projects)
Run dev using tool mode (avoids uv project mode):
cd .\beeware\Projects
uv run --no-project --with briefcase briefcase dev
Python version note (important)
If uv installs Python 3.14.x by default (e.g.,
uv python install 3), on Windows Toga’s WinForms backend (toga-winforms) depends onpythonnet>=3.0.0, andpythonnetcurrently may not provide wheels compatible with Python 3.14 yet. That causes pip resolution to fail duringbriefcase dev.Pinning to Python 3.13 resolves this in my environment:
uv python install 3.13
uvx --python 3.13 briefcase@latest dev
Question for the author/maintainers
uvx briefcase ...) oruv run --no-project --with briefcase ...(as above)?pythonnetsupports Python 3.14?Thanks!
freakboy3742 commentedon Jan 5, 2026
@Shuuen-Yukibi At present, we don't have any advice on the use of uvx with Briefcase. We're not opposed to make changes to accomodate the use of uv or uvx; and some recent changes that we've made, and some improvements that are on our todo list should make compatibility with uvx easier. In the meantime, we're not testing for the use of uv or uvx, so we can't make any guarantees or suggestions about how it operates.
As for Pythonnet - yes, pinning to 3.13 is the only viable option until pythonnet/pythonnet#2610 / pythonnet/pythonnet#2611 is resolved.
freakboy3742 commentedon Jun 16, 2026
As of v0.4.0, Briefcase can now be used with
uvx. (e.g.,uvx briefcase new,uvx briefcase dev,uvx briefcase run, etc)uv runis difficult to make work, because apyproject.tomlfile contains the code and requirements for a specific app, which won't includebriefcase. I'm not sure if there's any way to reconcile this - effectively we would need to define a "briefcase" environment that only includes Briefcase and it's dependencies;When running in uvx, Briefcase will still be using the built-in environment management provided by
pipandvenv. #2231 describes the request for Briefcase to useuv` to create environments.On that basis, this has essentially become a documentation issue, describing how to run Briefcase with
uvx. Following our triage process, I'm going to close this ticket in favour of #2884 as a documentation ticket.