Better version management with `uv` workspaces in a Polylith setup

[extreme4all]

Hey,
We’ve been using the Polylith architecture for a while and one pain point is version management.
Each project has its own pyproject.toml, so dependency versions can easily drift apart.

I’m wondering if we could use uv workspaces to manage versions more centrally, so shared and project-specific dependencies stay in sync.

• components are like a package with their own unique dependencies
• bases use components and may have their own unique dependencies
• projects tie bases & components together & are used build a container

This video by Arjan Codes shows how to use uv workspace:
The Best Way to Share Code Between Python Apps

Has anyone tried something like this, or found a clean way to handle shared dependencies across projects in a Polylith repo?

my project:
OSRS bot_detector

[DavidVujic]

Hello @extreme4all,

you can use uv workspaces with Polylith already. I think I've set it up like that in this example repo. You'll have one lock file across all the projects. Is that what you mean?

[DavidVujic]

The approach that I recommend for Polylith is to treat the projects as workspaces, instead of having a full-blown pyproject.toml in each component.

[extreme4all]

yes so today i have the dependencies in each project, which is a bit cumbersome ...

[extreme4all]

so if for example my base/database has the database requirements attached to it than every project that needs the database component wouldn't need to specify its version etc

[DavidVujic]

I think adding this to your root pyproject.toml will simplify the dependency management:

[tool.uv.workspace]
members = ["projects/*"]

Usually a base is a 1:1 with a project, so in this case I think the amount would be the same. But if you have a component that is used in several projects, then yes, every project need the dependency. But with the uv workspace added to Polylith it shouldn't be that much of a problem. You can have a loose specification in the relevant projects, and let the lock file (that is shared by all) decide the specifics.

[DavidVujic]

Maybe I misunderstand what you mean, please let me know if so.

The reasoning I have had about this is that several components might have the same third-party dependency (such as Pydantic or something common) and it will be the same kind of headache to have those in sync as with having it all in a project.

[extreme4all]

yeah on the surface that is what uv workspaces seem to fix, where you can have global dependencies & local but you are right its exchanging one issue with the other ...

so i guess what would be cool is if each base, component & project could have a pyproject.toml as if its a workspace and we just

/bases
  /base-x
    /pyproject.toml
       dependency: database & component-x
  /base-y 
    /pyproject.toml
      dependency: database & component-y
/components
  /database
    pyproject.toml
     dependency: aiomysql, sqlalchemy
  /component-x
    /pyproject.toml
       dependency: aiohttp
  /component-y
    /pyproject.toml
      dependency: aiokafka
/projects
  /project-x
    /pyproject.toml
     dependency: base-x
  /project-y
    /pyproject.toml
      dependency: base-y

pyproject.toml
dependencies: bases/*, components/*, projects/*

[DavidVujic]

I'll give it a try, it is mainly the poly check and poly libs commands that would be adjusted a bit. It would be a uv-only feature then, I will investigate how it can be done in a simple way

In total, I see the risk of adding more boilerplate than with the current setup, because I think you still need to have a valid pyproject.toml in there (with the required metadata, and such). Possibly also a README.

If you would use workspaces with the existing way Polylith does:

the root pyproject.toml

[tool.uv.workspace]
members = ["projects/*"]

The root folder would also have an uv.lock file for the entire workspace. No need for project-specific lock files.

Each project only need to specify the dependency (without the version if you like):

dependencies = [
    "sqlalchemy"
]

The version is in the root-level uv.lock file. It looks like you deploy your services using uv sync, and I think that will work out of the box. Just add (COPY) the root-level lock file to the docker container.

If you build wheels: then you will need to have a proper project-specific pyproject.toml with versions, at least if I understand how uv handles it. I think you can export the deps to a requirements.txt to make that work there too.

[DavidVujic]

I have updated this repo, and also added some docs about uv workspaces: https://github.com/DavidVujic/python-polylith-example-uv?tab=readme-ov-file#using-uv-workspaces

I will also investigate how we can do this in the way you suggest!

[extreme4all]

i'll play around with it as well to see if i can find a good workflow