What is an Nx Python monorepo and how does Nx model Python projects?
An Nx Python monorepo is a single repository where each Python service or library is an Nx project. Nx discovers projects in two ways: a project.json file in the project directory, or configuration that a plugin infers from files such as pyproject.toml. Each project exposes targets such as lint, test and build. Each target is a thin wrapper around a command you would otherwise type by hand, such as uv run pytest or poetry build.
Nx never installs or resolves Python dependencies. It does not read lockfiles to pick versions, and it does not create virtual environments. The core rule follows from that:
- The package manager owns dependency resolution. uv or Poetry decides what gets installed.
- Nx owns orchestration. That covers the project graph, affected detection, task running and caching.
Keeping this boundary clear matters when debugging. A wrong package version is a uv or Poetry problem. A task that ran when it should not have, or was skipped when it should have run, is an Nx graph or cache problem.
The community-maintained nx-python plugin adds three things on top of this:
- Generators that scaffold new Python projects.
- Executors that wrap uv or Poetry commands.
- Graph inference that reads path dependencies in
pyproject.tomlto build edges between projects.
The plugin is not part of core Nx, and its option names have changed over time. Check its documentation for the current options before you copy configuration from older examples.
You do not need the plugin to start. The project.json example below defines its targets with the built-in nx:run-commands executor, which runs each command from the project root. Nx can schedule and cache these targets like any others. Without the plugin, you declare dependencies between projects yourself, using implicitDependencies in project.json.
{
"name": "orders-api",
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"projectType": "application",
"sourceRoot": "services/orders-api/src",
"implicitDependencies": ["shared-models"],
"targets": {
"lint": {
"executor": "nx:run-commands",
"cache": true,
"options": {
"command": "uv run ruff check .",
"cwd": "{projectRoot}"
}
},
"test": {
"executor": "nx:run-commands",
"cache": true,
"options": {
"command": "uv run pytest",
"cwd": "{projectRoot}"
}
},
"build": {
"executor": "nx:run-commands",
"cache": true,
"dependsOn": ["^build"],
"outputs": ["{projectRoot}/dist"],
"options": {
"command": "uv build",
"cwd": "{projectRoot}"
}
}
}
}
A plugin-free project.json: nx:run-commands targets wrap uv commands, cwd sets the project root, and implicitDependencies declares a graph edge by hand.
Why would a team mix uv and Poetry in one workspace, and who is this for?
Few teams choose a mixed toolchain on purpose. It usually builds up over time, and the causes are predictable.
The most common one is age. Services written a few years ago have a pyproject.toml with a [tool.poetry] section and a committed poetry.lock, and their CI scripts are built around Poetry. They run in production and nobody wants to touch them unless there is a reason. Meanwhile, new services get started with uv because it resolves and installs dependencies quickly and handles Python versions itself. A few quarters later, the repository holds both.
The second cause is consolidation. An acquisition, a reorg, or a decision to merge several repositories into one brings in code with its own lockfiles and conventions. Rewriting every package manager configuration during the merge adds risk to a move that is already disruptive, so teams keep each tool as it was.
This guide is for backend and platform teams that have several Python services, share internal libraries between them, and want CI to build and test only what a change affects. If you have one service, or services that share no code, Nx brings little benefit to justify its cost.
Treat the mixed setup as a transitional state, not a target architecture. Two lockfile formats mean two resolvers, two upgrade workflows, and two sets of CI caches. Shared libraries also have to stay installable from both tools. Nx makes that period manageable. It does not make it free.
How do uv workspaces differ from a Poetry monorepo?
The two tools disagree on what a "workspace" is. In a uv workspace, the root pyproject.toml lists member packages, and uv resolves all of them together into one uv.lock at the root. Every member gets the same version of every shared dependency. Poetry has no equivalent. Each project keeps its own poetry.lock, and a local library is pulled in through a path dependency. That library's requirements are then resolved again inside every consumer's lockfile.
| Concern | uv workspace | Poetry projects |
|---|---|---|
| Version conflicts | Surface immediately; one member can block another | Isolated per project; can surface later at runtime |
| Upgrades | One lock update covers every member | Repeated per project |
| Version drift | Not possible within the workspace | Accumulates unless enforced |
| Install duplication | One shared environment by default | One environment per project |
| CI cost | One resolve, but any lock change can mark all members affected | Smaller, independent installs that multiply with project count |
Layout options
(a) uv workspace plus independent Poetry projects. Migrated services and shared libraries sit in the uv workspace. Poetry services consume those libraries through path dependencies. Choose this when the shared libraries already work under uv, the uv-side services can agree on dependency versions, and you want to migrate toward uv over time.
(b) Fully independent environments for both tools. Each uv project has its own lockfile, just like each Poetry project. Choose this when services pin conflicting versions, are owned by different teams, or need separate release cadences. You give up one-step upgrades in exchange for isolation.
How do you set up a mixed uv and Poetry workspace with Nx?
Take a three-project layout: apps/api (uv), apps/worker (Poetry) and libs/shared, a plain package with its own pyproject.toml and a standard build backend. Each project directory also holds a project.json. The shared library has no lockfile because it is consumed by path and never installed on its own.
Each tool declares the path dependency in its native syntax. In the API, list shared under [project] dependencies and map it in [tool.uv.sources] to { path = "../../libs/shared", editable = true }. In the worker, add shared = { path = "../../libs/shared", develop = true } under [tool.poetry.dependencies]. Editable installs matter here. Without them, a change to the library is invisible until you reinstall it.
Define lint, test and build in each project.json with the nx:run-commands executor and cwd set to the project root:
- API:
uv run ruff check .,uv run pytestanduv build - Worker: the same commands prefixed with
poetry run, pluspoetry build
Nx never resolves packages. It only decides what to run and in what order.
Nx does not read path dependencies from pyproject.toml by default. A Python plugin may infer the edges. If you have no plugin, add "implicitDependencies": ["shared"] to both app projects. Then run nx graph and confirm that api and worker each have an edge to shared. If an edge is missing, Nx will not rerun tests for that app when the library changes.
The resulting graph and ownership boundaries:
- Nx: orchestrates tasks and caching across all three projects.
api: uv ownsuv.lock; depends onshared.worker: Poetry ownspoetry.lock; depends onshared.shared: consumed by path, with no lockfile.
{
"name": "worker",
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"projectType": "application",
"sourceRoot": "apps/worker",
"implicitDependencies": ["shared"],
"targets": {
"lint": {
"executor": "nx:run-commands",
"options": {
"command": "poetry run ruff check .",
"cwd": "apps/worker"
}
},
"test": {
"executor": "nx:run-commands",
"options": {
"command": "poetry run pytest",
"cwd": "apps/worker"
}
},
"build": {
"executor": "nx:run-commands",
"outputs": ["{projectRoot}/dist"],
"options": {
"command": "poetry build",
"cwd": "apps/worker"
}
}
}
}
apps/worker/project.json wraps Poetry commands in nx:run-commands targets and declares an implicit dependency on shared, so nx graph shows the worker-to-shared edge without a Python plugin; the uv-based api project.json follows the same pattern.
How should you configure Nx caching and affected runs for Python?
Nx decides whether to replay a cached result by hashing the inputs you declare, so the inputs must describe everything that can change a Python result. Define a shared named input in nx.json, for example pythonSource, that covers {projectRoot}/**/*.py, {projectRoot}/pyproject.toml, and the project's lockfile (uv.lock or poetry.lock). Add {workspaceRoot}/.python-version and any environment variables that change behaviour, such as PYTHONHASHSEED or a settings-module variable, as env inputs. Negated patterns like !{projectRoot}/.venv/** and !{projectRoot}/**/__pycache__/** keep interpreter artifacts out of the hash. Without them, every local install changes the cache key.
Declare outputs so a cache hit restores the artifacts as well as the logs. Typical outputs are {projectRoot}/dist for wheels and {projectRoot}/coverage or a coverage.xml path for test reports.
Incomplete inputs cause the most damaging failure. Suppose poetry.lock is missing from worker's test inputs. A dependency bump then leaves the hash unchanged, and Nx replays a green test run that never executed against the new code. Task dependencies that point at shared's inputs prevent the same problem across projects.
In CI, run nx affected -t test lint against the merge base. Use nx show projects --affected to get the project list, then install only those environments, for example uv sync --package api or poetry install inside worker, instead of syncing every project.
Affected detection only sees dependencies that Nx can infer or that you declare. importlib calls, plugin entry points, and packages that are loaded only at runtime are invisible to it. Declare those dependencies explicitly, or affected runs will skip projects that are actually affected.
// nx.json (Nx parses this file as JSONC, so comments are allowed)
{
"namedInputs": {
// Everything that can change a Python result for one project
"pythonSource": [
"{projectRoot}/**/*.py",
"{projectRoot}/pyproject.toml",
// Include both lockfiles; whichever the project lacks simply matches nothing
"{projectRoot}/uv.lock",
"{projectRoot}/poetry.lock",
"{workspaceRoot}/.python-version",
{ "env": "PYTHONHASHSEED" },
{ "env": "DJANGO_SETTINGS_MODULE" },
// Keep local interpreter artifacts out of the hash
"!{projectRoot}/.venv/**",
"!{projectRoot}/**/__pycache__/**"
]
},
"targetDefaults": {
"test": {
"cache": true,
// ^pythonSource: a change in a dependency such as shared invalidates this project's tests too
"inputs": ["pythonSource", "^pythonSource"],
// Restored on a cache hit, along with the logs
"outputs": ["{projectRoot}/coverage"]
},
"lint": {
"cache": true,
"inputs": ["pythonSource"]
},
"build": {
"cache": true,
"dependsOn": ["^build"],
"inputs": ["pythonSource", "^pythonSource"],
"outputs": ["{projectRoot}/dist"]
}
}
}
An nx.json that hashes Python sources, pyproject.toml, lockfiles, .python-version and behaviour-changing env vars, excludes .venv and pycache, and declares the dist and coverage outputs.
When should you avoid Nx for a Python monorepo, and what does it cost?
The mixed setup has ongoing costs, and they do not shrink as the workspace matures.
| Cost | Why it persists |
|---|---|
| Two package managers | Two mental models, two lockfile formats and two sets of CI cache keys to maintain |
| Shared uv lockfile | One member pinned to a conflicting dependency blocks upgrades for every other member |
| Node.js toolchain | package.json, node_modules and Nx upgrades become work for a team that writes only Python |
| Community plugin | It can lag behind new uv, Poetry or Nx releases, so you either wait or patch it yourself |
| Type checkers and IDE | Mypy, pyright and the editor must each be pointed at the correct interpreter for each project |
In return you get affected-only CI, cache hits on projects that did not change, and one task interface (nx test, nx lint) no matter which tool built the environment. These savings grow with the number of projects and how often they change.
Illustrative estimate (assumed numbers, not a benchmark): weekly CI minutes saved = PRs per week × untouched projects per PR × CI minutes per project. Assuming 40 PRs, 6 untouched projects per PR and 3 minutes each, that is 40 × 6 × 3 = 720 minutes. Subtract the engineering hours you spend maintaining Nx, the plugin and two lockfile workflows.
Rule of thumb: if a small team runs only a few services, there are almost no untouched projects per PR, so the savings are close to zero. In that case, standardize on one package manager and its native workspace support. Add Nx when CI time or cross-team coordination becomes a measurable problem.
What are the alternatives, and how do you migrate incrementally?
Three alternatives come up most often, and each trades a different amount of setup for a different level of precision.
| Option | What it handles well | Where it falls short |
|---|---|---|
| Single uv workspace, no Nx | One lockfile, one resolver, fast installs, minimal config | Requires every service to adopt uv. No task cache or dependency-aware test selection. |
| Poetry per project + CI path filters | Each team keeps full control. Easy to start. | Path globs drift from real imports, so shared-library changes get missed or over-triggered. |
| Other general build orchestrators | Hermetic builds, fine-grained caching, strong multi-language support | Higher adoption cost. Build files must declare dependencies explicitly, which is a larger rewrite than Nx inferring them. |
The path-filter option breaks down quietly. CI stays green while a change to a shared package skips the services that import it. That gap is usually the first concrete reason teams look at a graph-aware tool.
Migrating incrementally
- Wrap, don't convert. Add an Nx project definition to each service whose targets call the existing commands (
poetry run pytest,uv run pytest). No lockfiles change, so a broken step is easy to bisect. - Validate the graph and cache. Confirm that Nx sees the internal dependencies you expect. Then run a target twice and check that the second run is a cache hit. Edit a shared library and check that the affected set includes its consumers. Fix inputs and outputs before anyone relies on the cache.
- Move Poetry services to uv one at a time, if at all. Make each move a separate pull request with its own lockfile diff. Keeping the conversion out of the Nx rollout means a resolution change can't be confused with an orchestration bug. It also means services that work well on Poetry can stay on it.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to nx python monorepo, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.