Python

Migrating to a uv Workspace: The Traps, in the Order They Bite

The migration itself is short: two packages, one workspace, one lockfile. What eats the afternoon is the three failures in front of it — a root that uv tries to build as a package, an init default that silently picks a Python you do not have, and a flag that was never a flag. This guide runs the migration on the box and keeps every failure in, quoted verbatim, because the failures are the useful part.

Written November 6, 2026 · Tested with Python 3.12.3 · 11 min read

By the end of this guide
  • The migration, end to end
  • One external dependency proves the shared lockfile
  • Member-to-member versions: no pin needed

Edited November 18, 2026

What you will build

Two standalone library packages, acme-core and acme-cli, migrated into a single uv workspace: one uv.lock at the root, no member lockfiles, per-member commands with uv run --package from any directory, and editable member-to-member imports. One external dependency, click, is locked in the workspace to prove the shared lockfile holds a third-party package, not just the two members.

The starting shape is the common one: two packages that already exist, with acme-cli depending on acme-core through a path source. The end shape is the workspace: the same dependency declared with { workspace = true }, and a virtual root that owns no package of its own.

Tested with uv 0.12.23 and Python 3.12.3 on Ubuntu 24.04.

This guide is a failure-mode catalog, not a setup guide. The workspace docs already explain how to create a workspace; what they do not teach is the order in which the migration fails. The three traps below are in bite order: the first thing that fails, then the next, then the next.

Trap 1: the root must be virtual

Trap
The most likely first failure is the root itself. A workspace needs a root, and the root is also a workspace member — but if the root has a [project] table and no source directory to match it, uv sync tries to build the root as a package and fails at the build step. This is the root that fails:
TOML
[project]
name = "acme-root"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []

[build-system]
requires = ["uv_build>=0.12.23,<0.13.0"]
build-backend = "uv_build"

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

[tool.uv.sources]
acme-cli = { workspace = true }
acme-core = { workspace = true }

uv sync --python 3.12 resolves all three packages, then fails building the root:

Output
Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
Creating virtual environment at: .venv
Resolved 3 packages in 1ms
   Building acme-root @ file:///home/user/uv-probe-2026-11-06/trap1
error: Failed to build `acme-root @ file:///home/user/uv-probe-2026-11-06/trap1`
  cause: Expected a Python module at: src/acme_root/__init__.py

The [project] table is the defect. It tells uv the root is a package, and uv_build then looks for the package source at src/acme_root/__init__.py, which does not exist. There is no source directory to create: the root owns no code, and giving it a dummy module would only paper over the mistake.

The fix is a virtual root: no [project] table, no [build-system] table, just the workspace declaration. The [tool.uv] package = false line says the root is not a package at all:

TOML
[tool.uv]
package = false

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

[tool.uv.sources]
acme-cli = { workspace = true }
acme-core = { workspace = true }

With that root, uv sync resolves two packages instead of three and never tries to build the root. The docs state the rule behind this: a dependency with a workspace source can be virtual if it sets tool.uv.package = false, and workspace members that are not dependencies can be virtual by default. A root that owns no code is the case the setting exists for.

Teach this first. Everything after it assumes the root is virtual, and a [project] root fails before any member behavior can be observed.

Trap 2: uv init defaults requires-python to >=3.13

Trap
The second failure is quieter, which is why it costs more time. uv init scaffolds a member with requires-python = ">=3.13":
Output
Initialized project `trap2-pkg` at `/home/user/uv-probe-2026-11-06/trap2`
requires-python = ">=3.13"

The box interpreter is Python 3.12.3. Nothing fails yet. uv lock with no --python flag resolves the project — and silently picks a Python you did not ask for:

Output
Using CPython 3.13.14
Resolved 1 package in 15ms

uv downloaded a managed CPython 3.13.14 and locked against it. The lockfile now requires >=3.13. The failure lands one command later, when you sync against the interpreter you actually have:

Output
Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
error: The requested interpreter resolved to Python 3.12.3, which is incompatible with the project's Python requirement: `>=3.13` (from `project.requires-python`)

The lock succeeded and the sync failed, and the error names the requirement, not the cause. The cause is the default in the scaffolded pyproject.toml, two commands back.

The fix is to pin the Python at creation time, before anything is locked:

Bash
uv init --lib --name acme-core --python 3.12 libs/core
uv init --lib --name acme-cli --python 3.12 libs/cli

Both members then carry requires-python = ">=3.12", and uv lock --python 3.12 resolves against the box interpreter:

Output
Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
Resolved 2 packages in 2ms

Two rules follow. First, never run uv lock without --python on a machine whose interpreter is older than the scaffold default — the lock will succeed against a downloaded interpreter and the sync will fail against yours. Second, workspaces enforce a single requires-python for the whole workspace, taking the intersection of all members' values, so the pin has to agree across members; one member left at >=3.13 poisons the intersection for the rest.

Trap 3: uv init rejects --no-pin

Trap
The third failure is the fastest and the most confusing, because the error suggests a flag that is almost the one you typed. --no-pin is not a uv init flag:
Terminal
$ uv init --lib --no-pin --name trap3-pkg trap3
error: unexpected argument '--no-pin' found

  tip: a similar argument exists: '--no-pin-python'

Usage: uv init --lib --no-pin-python [PATH]

For more information, try '--help'.

Exit code 2, and no scaffold is written — the directory does not exist afterward. The similar argument, --no-pin-python, does something else entirely: it stops uv init from creating a .python-version file for the project. It has nothing to do with pinning dependencies, and passing it does not change what uv init writes into requires-python. If you typed --no-pin because you wanted to stop uv pinning something, there is nothing to stop: uv init does not pin dependency versions, and the Python floor comes from the --python flag in Trap 2, not from a pin flag.

The migration, end to end

With the traps out of the way, the migration itself is four steps. The starting shape is two standalone libraries created with uv init --lib --python 3.12, each with its own pyproject.toml, and acme-cli depending on acme-core through a path source — the pre-migration shape:

TOML
[tool.uv.sources]
acme-core = { path = "../core", editable = true }

The core library is one function:

Python
def greet():
    return "core-ok"

The CLI imports it:

Python
from acme_core import greet

def main():
    print(greet() + " cli-ok")

Step one is the virtual root from Trap 1, written at the repository root. Step two is switching the CLI's source entry from the path to the workspace member:

TOML
[tool.uv.sources]
acme-core = { workspace = true }

The dependency declaration itself does not change — dependencies = ["acme-core"] in the CLI stays exactly as it was. Only the source moves. Step three is the lock and sync, run once, from the root:

Bash
uv lock --python 3.12
uv sync --python 3.12
Output
Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
Creating virtual environment at: .venv
Resolved 2 packages in 5ms
   Building acme-cli @ file:///home/user/uv-probe-2026-11-06/mig/libs/cli
   Building acme-core @ file:///home/user/uv-probe-2026-11-06/mig/libs/core
      Built acme-cli @ file:///home/user/uv-probe-2026-11-06/mig/libs/cli
      Built acme-core @ file:///home/user/uv-probe-2026-11-06/mig/libs/core
Prepared 2 packages in 22ms
Installed 2 packages in 3ms
 + acme-cli==0.1.0 (from file:///home/user/uv-probe-2026-11-06/mig/libs/cli)
 + acme-core==0.1.0 (from file:///home/user/uv-probe-2026-11-06/mig/libs/core)

Step four is the proof. Exactly one lockfile exists, at the root:

Output
./uv.lock
ROOT LOCKFILE PRESENT
NO MEMBER LOCKFILE core
NO MEMBER LOCKFILE cli

A member command runs from any directory in the workspace — here, from inside the other member's directory:

Bash
cd libs/core
uv run --package acme-cli python -c "from acme_cli import main; main()"
Output
core-ok cli-ok

And the member-to-member import is editable, not a copied install. The imported module resolves to the source tree:

Output
/home/user/uv-probe-2026-11-06/mig/libs/core/src/acme_core/__init__.py

Edit libs/core/src/acme_core/__init__.py and the next uv run picks the change up with no reinstall. The docs state this directly: dependencies between workspace members are editable, and uv uses editable installation for workspace packages by default.

One more check belongs in the proof: uv workspace list prints the members, root included only if it is a package. With a virtual root, the list is the two libraries:

Output
acme-cli
acme-core

Note what uv init stamps into each member pyproject.toml that the listings above omit: an authors block taken from the machine's git config. Strip or replace that block before publishing example pyproject.toml files — it is your name and address, not part of the migration.

One external dependency proves the shared lockfile

The migration above is stdlib-only, and a stdlib-only workspace does not prove the lockfile does anything a pair of path dependencies could not do. So the workspace locks one external dependency: click, added to acme-cli from the root:

Bash
uv add --package acme-cli click
Output
Resolved 3 packages in 93ms
   Building acme-cli @ file:///home/user/uv-probe-2026-11-06/mig/libs/cli
      Built acme-cli @ file:///home/user/uv-probe-2026-11-06/mig/libs/cli
Prepared 1 package in 13ms
Uninstalled 1 package in 1ms
Installed 2 packages in 9ms
 ~ acme-cli==0.1.0 (from file:///home/user/uv-probe-2026-11-06/mig/libs/cli)
 + click==8.5.0

The lockfile now holds three packages, still in the single root uv.lock, with click pinned to 8.5.0 against the >=8.5.0 constraint uv add wrote. The tree shows the whole workspace at once:

Output
Resolved 3 packages in 2ms
acme-core v0.1.0
acme-cli v0.1.0
├── acme-core v0.1.0
└── click v8.5.0

The CLI's pyproject.toml after the migration, author block removed, is the complete member file:

TOML
[project]
name = "acme-cli"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["acme-core", "click>=8.5.0"]

[build-system]
requires = ["uv_build>=0.12.23,<0.13.0"]
build-backend = "uv_build"

[tool.uv.sources]
acme-core = { workspace = true }

Note what is absent: click has no [tool.uv.sources] entry, because it comes from PyPI, and acme-core has no version pin, because it comes from the workspace. That split is the whole member-to-member version story, and it is the next section.

Member-to-member versions: no pin needed

A member dependency needs two lines: the plain name in dependencies, and the workspace source entry. No version is required. The docs say uv selects the member that matches the dependency name, and the probe confirms it: dependencies = ["acme-core"] with acme-core = { workspace = true } resolves to the local member, editable, with no version anywhere in the declaration.

A pin is allowed — the docs' own example shows dependencies = ["foo==0.1.0"] alongside foo = { workspace = true } — but it buys nothing here. The member's version is the version; pinning it restates a fact the workspace already knows, and leaves a second place to update when the member version moves. Leave the version out unless something outside the workspace needs to read it.

Two related rules from the same docs pages are worth knowing before the workspace grows. First, root tool.uv.sources definitions apply to all members unless a member overrides the same dependency in its own tool.uv.sources — and a member that provides its own entry ignores the root entry for that dependency even if the member's source is limited by a marker that does not match the current platform. Audit sources per member, not once at the root. Second, the docs state the boundary plainly: workspaces are not suited for members with conflicting requirements, or members that want a separate virtual environment each. In that case path dependencies are the preferred alternative, with the stated cost that uv run --package stops working and commands must run from the relevant package directory.

What breaks, and the fix

| Error | Cause | Fix | | error: Failed to build ... cause: Expected a Python module at: src/acme_root/__init__.py | Root has a [project] table but no source directory | Virtual root: [tool.uv] package = false, no [project] or [build-system] | | error: The requested interpreter resolved to Python 3.12.3, which is incompatible with the project's Python requirement: >=3.13 | uv init defaulted requires-python to >=3.13; uv lock resolved against a downloaded managed 3.13.14 | Create members with uv init --python 3.12; pass --python 3.12 to uv lock and uv sync | | error: unexpected argument '--no-pin' found | --no-pin is not a uv init flag | Drop it; the nearest real flag, --no-pin-python, only controls the .python-version file | | uv: command not found | ~/.local/bin is not on the shell PATH | Export ~/.local/bin first; uv installs user-space, not system-wide | | core-ok cli-ok never prints; ModuleNotFoundError: acme_core | CLI still points at the path source, or the root is not a workspace | Switch the source entry to { workspace = true } and check the root has [tool.uv.workspace] |

Frequently asked questions

Can the root be a real package instead of a virtual root?

Yes — the docs' own example has a root package (albatross) with libraries under packages/. A real root is the right shape when the root owns code. A virtual root is the right shape when it does not. The trap is the middle shape: a [project] root with no source directory. Pick one side or the other; the middle fails at the build step with the Expected a Python module error in Trap 1.

What if two members need different versions of the same third-party package?

Then a workspace is the wrong shape. The docs say workspaces are not suited for members with conflicting requirements, and the single lockfile is the reason: one lockfile means one resolved version per package for the whole workspace. Use path dependencies instead, and accept that uv run --package goes away.

What if one member needs a newer Python than the rest?

The workspace enforces a single requires-python, the intersection of all members' values. Testing one member on a Python the rest do not support needs uv pip in a separate virtual environment, per the docs. Do not widen one member's floor and expect the rest to follow; the intersection is what binds.

Does the workspace stop one member importing another member's dependencies?

No. Python provides no dependency isolation, and the docs say so: uv cannot ensure that a package uses its declared dependencies and nothing else, and for workspaces specifically it cannot ensure that packages do not import dependencies declared by another member. The single shared environment is a leak by design. The check is yours: import each member in isolation and confirm it only touches what it declares.

Where is the full workspace setup guide?

In the uv docs, linked below. This guide is the failure catalog for a migration you already decided to do — the three ways it bites first, in the order they bite, with the verbatim errors so you can recognize each one when it appears.

Is there a companion migration guide in this set?

Turning strict On in a Codebase That Never Had It: TypeScript 5.9 to 7.0 is the same kind of job in a different stack: a setting the codebase never turned on, a compiler that reports the backlog all at once, and a fix order that works through the error classes. Read it for the pattern when your own migration is a language setting rather than a workspace layout.

Sources

  • Astral, Using workspaces — workspace definition, single lockfile, uv run and uv sync with --package, member and exclude globs, { workspace = true } sources, sources inheritance and the marker override rule, the single requires-python intersection, the not-suited boundary, and the no-isolation caveat.
  • Astral, Managing dependencies — member dependencies as { workspace = true }, workspace members always editable, virtual dependencies with tool.uv.package = false, and uv add writing the constraint.
  • Astral, Structure and files — the uv.lock as the single cross-platform lockfile next to the root pyproject.toml, and the .venv managed environment.

Keep Exploring