@mgwilt/nx-uv

Nx plugin for running uv workflows in Nx monorepos.

Why this plugin exists

Nx provides a consistent task graph, caching, and affected-based CI so large repos run faster and more predictably. A common operational gap is that Python workflows powered by uv often stay in separate shell scripts and one-off CI jobs, so they miss the same build/test orchestration used by the rest of the monorepo.

@mgwilt/nx-uv bridges that gap by turning common uv workflows into Nx-native targets and adding inference/generators so teams can standardize command execution, reduce bespoke pipeline logic, and manage Python alongside other stacks in a single CI model instead of maintaining a parallel toolchain path.

When to use this plugin

• Run uv commands through Nx targets instead of ad-hoc shell scripts.
• Infer useful uv targets from existing pyproject.toml files.
• Scaffold uv-ready Python projects and workspace config.
• Keep Python work in the same task graph, caching, and CI flow as the rest of your monorepo.

Tools

• Executors for uv command families:
  • @mgwilt/nx-uv:project
  • @mgwilt/nx-uv:uv
  • @mgwilt/nx-uv:pip
  • @mgwilt/nx-uv:tool
  • @mgwilt/nx-uv:python
  • @mgwilt/nx-uv:auth
  • @mgwilt/nx-uv:cache
  • @mgwilt/nx-uv:self
  • @mgwilt/nx-uv:studio
• Generators:
  • @mgwilt/nx-uv:workspace
  • @mgwilt/nx-uv:project
  • @mgwilt/nx-uv:integration
  • @mgwilt/nx-uv:convert
• Nx plugin inference (createNodesV2) for pyproject.toml.

Install

Prerequisites:

• Nx workspace
• uv installed and available on PATH

Install the plugin:

pnpm add -D @mgwilt/nx-uv

Interactive studio (TUI)

Launch the interactive monorepo manager directly with pnpm dlx (recommended):

pnpm dlx -p @mgwilt/nx-uv nx-uv tui

Shorthand (when supported by your pnpm version/environment):

pnpm dlx @mgwilt/nx-uv tui

The studio provides:

• Workspace setup and inference configuration
• Python app/lib/script generation
• Integration template scaffolding
• Convert existing projects to nx-uv defaults
• Nx target execution across all projects
• Ad-hoc uv command execution
• Preview-before-apply flow for mutating actions

Optional flags:

• --cwd=<path> scan and manage a workspace from a specific directory
• --readonly disable mutation/apply operations
• --initial-view=<dashboard|workspace|project|integration|convert|inference|tasks|uv>

If plugin inference is configured with includeGlobalTargets: true and a root uv workspace exists, the root inferred project also gets a <targetPrefix>tui target (for example uv:tui).

Brand new monorepo example

This walkthrough creates a new Nx monorepo and uses this plugin to scaffold a working uv + Python example.

1. Create a new workspace:

pnpm create nx-workspace@latest acme-monorepo --preset=ts --packageManager=pnpm --nxCloud=skip --interactive=false
cd acme-monorepo

2. Install this plugin and initialize workspace-level uv config:

pnpm add -D @mgwilt/nx-uv
pnpm nx g @mgwilt/nx-uv:workspace --name=acme --membersGlob='packages/py/*'

3. Generate a Python app and scaffold integrations:

pnpm nx g @mgwilt/nx-uv:project api --projectType=app --directory=packages/py
pnpm nx g @mgwilt/nx-uv:integration --template=fastapi --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=github

Expected file tree (key files) after step 3:

acme-monorepo/
├── nx.json
├── package.json
├── pyproject.toml
├── .github/
│   └── workflows/
│       └── uv-ci.yml
└── packages/
    └── py/
        └── api/
            ├── README.md
            ├── pyproject.toml
            ├── main.py
            ├── Dockerfile.fastapi
            ├── src/
            │   └── api/
            │       ├── __init__.py
            │       └── main.py
            └── tests/
                └── test_smoke.py

4. Add runtime and dev dependencies with uv:

cd packages/py/api
uv add fastapi uvicorn
uv add --dev pytest ruff
cd ../../..

5. Run plugin-backed targets via Nx:

pnpm nx run api:sync
pnpm nx run api:uv
pnpm nx run api:run
pnpm nx run api:test
pnpm nx run api:build

At this point you have a working monorepo with:

• Root pyproject.toml and uv workspace members
• A generated api Python project under packages/py/api
• Generated FastAPI starter files and a GitHub Actions Nx-first CI template (test, lint, typecheck, build)
• Nx targets that run uv commands consistently in CI/local dev

Quick start (existing workspace)

1. Add the plugin to nx.json:

{
  "plugins": [
    {
      "plugin": "@mgwilt/nx-uv",
      "options": {
        "targetPrefix": "uv:",
        "inferencePreset": "standard",
        "includeGlobalTargets": false
      }
    }
  ]
}

2. (Optional, recommended for new repos) Initialize uv workspace config:

pnpm nx g @mgwilt/nx-uv:workspace --name=acme

3. Generate a Python project wired for uv + Nx:

pnpm nx g @mgwilt/nx-uv:project services/api --projectType=app

4. Run uv-backed targets:

pnpm nx run api:sync
pnpm nx run api:test
pnpm nx run api:build

Existing Python projects

If your repo already has pyproject.toml files, the plugin can infer targets (for example uv:sync, uv:run, uv:test) based on your configured targetPrefix and inference preset.

Customizing inferred targets

You can disable or override inferred targets in plugin options:

{
  "plugins": [
    {
      "plugin": "@mgwilt/nx-uv",
      "options": {
        "targetPrefix": "uv:",
        "inferencePreset": "standard",
        "inferredTargets": {
          "test": false,
          "lint": {
            "command": "run",
            "commandArgs": ["--", "ruff", "check", "src"]
          }
        }
      }
    }
  ]
}

Supported inferred target keys are: sync, run, lock, test, lint, build, tree, export, format, venv, publish.

Integration templates

Use integration templates to scaffold common uv ecosystem files for CI, containers, dependency automation, and notebook workflows.

How file output location works

• --project=<name> sets <baseDir> to that Nx project's root.
• --directory=<path> sets <baseDir> to that directory relative to workspace root.
• If neither is set, <baseDir> defaults to workspace root (.).
• Workspace-level templates always write to repo root, even if --project or --directory is provided.
• Workspace-level templates are:
  • github
  • gitlab
  • dependency-bots
  • pre-commit

Template matrix

| Template | Scope | Files generated | Best for | | --------------------- | -------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | alternative-indexes | baseDir | <baseDir>/uv.indexes.toml.snippet | Defining custom/internal Python indexes | | aws-lambda | baseDir | <baseDir>/Dockerfile.lambda | Packaging uv-based AWS Lambda workloads | | coiled | baseDir | <baseDir>/scripts/coiled-example.py | Starting distributed Python experiments with Coiled | | dependency-bots | workspace root | renovate.json, .github/dependabot.yml | Automated dependency update workflows with Renovate and Dependabot | | docker | baseDir | <baseDir>/Dockerfile | Containerizing a uv project with Docker | | fastapi | baseDir | <baseDir>/main.py, <baseDir>/Dockerfile.fastapi | Bootstrapping a FastAPI service with uv | | github | workspace root | .github/workflows/uv-ci.yml | GitHub Actions Nx-first CI starter using nx affected | | gitlab | workspace root | .gitlab-ci.uv.yml | GitLab CI/CD Nx-first CI starter using nx run-many | | jupyter | baseDir | <baseDir>/scripts/setup-jupyter-kernel.sh | Registering a uv-managed Jupyter kernel | | marimo | baseDir | <baseDir>/notebooks/example.marimo.py | Starting marimo notebook workflows | | pre-commit | workspace root | .pre-commit-config.yaml | Local code quality hooks for uv projects using pre-commit | | pytorch | baseDir | <baseDir>/uv.pytorch.toml.snippet | Configuring PyTorch index/source snippets |

Command examples for all templates

pnpm nx g @mgwilt/nx-uv:integration --template=alternative-indexes --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=aws-lambda --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=coiled --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=dependency-bots
pnpm nx g @mgwilt/nx-uv:integration --template=docker --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=fastapi --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=github
pnpm nx g @mgwilt/nx-uv:integration --template=gitlab
pnpm nx g @mgwilt/nx-uv:integration --template=jupyter --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=marimo --project=api
pnpm nx g @mgwilt/nx-uv:integration --template=pre-commit
pnpm nx g @mgwilt/nx-uv:integration --template=pytorch --project=api

Common options

• --overwrite=true replaces existing files instead of skipping them.
• --directory=<path> writes baseDir-aware templates into a non-project directory.
• --skipFormat=true skips formatter execution after generation.
• Prefer --project for app/lib scaffolds and no location flag for workspace-level templates.

Notes and pitfalls

• Templates are starter scaffolds; you should review and harden generated files for production use.
• Running the same template multiple times without --overwrite=true leaves existing files unchanged.
• Workspace-level templates are intentionally global and may affect repository-wide automation.

Compatibility and versioning

• Runtime uv compatibility checks verify that uv is available and executable.
• uv 0.9.x and 0.10.x are currently the tested ranges. Other versions log a warning and continue.

Troubleshooting

Nx plugin bootstrap failures

If quality:ci fails before running tasks with worker/bootstrap errors (for example Failed to load ... Nx plugin(s)), run:

pnpm quality:bootstrap
pnpm nx reset
pnpm quality:ci

If bootstrap still fails, run direct checks to isolate whether the issue is Nx plugin startup or project logic:

pnpm quality:fallback
pnpm --version
pnpm nx --version
node -v

E2E execution permissions

The e2e suite executes a temporary shim binary from the local filesystem. In restricted environments (for example noexec mounts or sandboxed process policies), e2e tests may be skipped when executable spawning is not permitted.

In CI, an all-skipped e2e run is treated as a failure by default. Set NX_UV_ALLOW_E2E_ALL_SKIPPED=1 only in known restricted CI environments where executable shim spawning is intentionally blocked.

LLM context files

This repository publishes LLM-friendly docs artifacts:

• llms.txt: concise index of high-signal project docs.
• llms-full.txt: expanded inline content for the same curated sources.

Regenerate and validate them with:

pnpm llms:generate
pnpm llms:check

Additional docs

• Documentation index
• Maintainer guide (quality gates, CI, release)
• Maintainer toolchain matrix
• Runbook: gate failed before tasks started
• Sample scaffolding patterns