How to run package scripts across a Python monorepo using uv run --project or the UV_PROJECT env var

Fix missing scripts outside package dirs in a Python monorepo: use uv run --project or set UV_PROJECT to resolve pyproject.toml [project.scripts] reliably anywhere.

Making Python project scripts work across a monorepo can be unexpectedly tricky. If each package under a shared workspace defines its own script in pyproject.toml, calling that script with uv run works inside the package, but the moment you step out to a sibling directory, the command is no longer discovered. Here is a concise, reproducible way to fix that without restructuring your repository.

Problem setup

Suppose a package under projects/ declares a script in its pyproject.toml. Inside that directory, uv run resolves and executes it. Outside, it can’t be found.

[project.script]
toolx = "toolx.handlers:entry"

From the package directory, this works:

$ uv run toolx

But invoking the same script from a sibling directory fails because the script isn’t visible outside the project boundary.

Why this happens

uv runs commands within a project root. When you are inside the package, its pyproject.toml is the active project and uv can resolve [project.script] entries like toolx. When you’re in another directory, the active project is different, so the script isn’t discovered. The command needs an explicit project context to find and run the script defined in that package’s pyproject.toml.

The fix

Point uv at the intended project root for the command you’re running. Use the --project option to tell uv which package directory should be treated as the project for script resolution.

If the package that defines toolx lives in ../pkg_toolx relative to your current working directory, run:

$ uv run --project ../pkg_toolx toolx

This instructs uv to treat ../pkg_toolx as the project root for the run, making the script available from anywhere in the workspace.

If you prefer a persistent setup, there is also a corresponding environment variable UV_PROJECT that can be set to a project root. With that in place, uv run will consistently resolve scripts against the specified project.

Why this matters

Monorepos often need scripts to be runnable from multiple places—whether you’re working in a sibling package, at the workspace root, or inside automation. Without specifying the project root, scripts only work from within their own package directories, which leads to inconsistent developer experience and fragile command invocation. Passing --project or setting UV_PROJECT ensures that script discovery is explicit and repeatable wherever you are in the tree.

Practical wrap-up

Keep your per-package script declarations in pyproject.toml as usual, for example:

[project.script]
toolx = "toolx.handlers:entry"

When you need to call that script from elsewhere in the monorepo, run:

$ uv run --project ../pkg_toolx toolx

Or set UV_PROJECT to a fixed project root if that matches your workflow. With a clear project root, uv run becomes predictable across the entire workspace.