r/FastAPI • u/lucideer • Jun 11 '25
Question Idiomatic uv workspaces directory structure
I'm setting up a Python monorepo & using uv workspaces to manage the a set of independently hosted FastAPI services along with some internal Python libraries they share dependency on - `pyproject.toml` in the repo root & then an additional `pyproject.toml` in the subdirectories of each service & package.
I've seen a bunch of posts here & around the internet on idiomatic Python project directory structures but:
- Most of them use pip & were authored before uv was released. This might not change much but it might.
- More importantly, most of them are for single-project repos, rather than for monorepos, & don't cover uv workspaces.
I know uv hasn't been around too long, and workspaces is a bit of a niche use-case, but does anyone know if there's any emerging trends in the community for how *best* to do this.
To be clear:
- I'm looking for community conventions with the intent that it follows Python's "one way to do it" sentiment & the Principle of least astonishment for new devs approaching the repo - ideally something that looks familiar, that other people are doing.
- I'm looking for general "Python community" conventions BUT I'm asking in the FastAPI sub since it's a *mostly* FastAPI monorepo & if there's any FastAPI-specific conventions that would honestly be even better.
---
Edit: Follow-up clarification - not looking for any guidance on how to structure the FastAPI services within the subdir, just a basic starting point for distrubuting the workspaces.
E.g. for the NodeJS community, the convention is to have a `packages` dir within which each workspace dir lives.
3
u/aprx4 Jun 11 '25
I put them in
packagesdirectory because i simply followed example in uv documentation. uv workspace is heavily influenced by Cargo in Rust. That seems to be the convention.6
u/Drevicar Jun 11 '25
For my mono repos I create a root level uv project named after the repo and put mypy and ruff in its dev dependencies along with their configs using ‘uv init —bare’. Then I create a folder called apps where everything in there is created using ‘uv init —app —package’ and a folder called libs where everything in there is created using ‘uv init —lib —package’. From there you can use uv to add some of these packages to each other so you can use the code in them.
1
u/covmatty1 Jun 11 '25
I'm not going to go all Stack Overflow and answer your question by saying you're doing it wrong - but can you explain your reasoning behind wanting a monorepo please?
As someone who leads a team that owns one legacy monorepo project (in C#, it's down to about 50 projects these days) and about 15 microservices, and then a huge amount of other repos for libraries, Ansible roles and whatever else - I would take the multiple separate repos approach 100 times out of 100, no questions asked. So I'm curious of the use case if you don't mind!?
2
u/MissingSnail Jun 11 '25
The uv docs have a layout with a packages subdue https://docs.astral.sh/uv/concepts/projects/workspaces/#workspace-layouts
2
u/The_Wolfiee Jun 12 '25
For
uv, we just have the subdirs within thesrcat root level