[RFC] Native Python support

[anthonyshew]

Turborepo now experimentally supports Python through uv workspaces: https://turborepo.dev/docs/guides/tools/python

We are rapidly iterating on this new capability, so you can expect improvements, missing functionality, and adjustments to come quickly.

Motivation

One of the longest-standing open requests in Turborepo is support for language toolchains beyond JavaScript: #683

This RFC introduces Python as a natively supported language in Turborepo, with uv as the package manager.

What drives this ask?

Monorepos can be large and do not have to contain just one language. It is common for a monorepo to contain multiple languages and toolchains. However, this creates complexity when managing workflows across them. Each toolchain creates its own partition within the monorepo, making interactions between each language's domain difficult to manage.

Turborepo users see what Turborepo offers for simplifying JavaScript and TypeScript workflows and want the same experience for every language in their repository. The canonical ask becomes, "How do I make turbo run lint run all the linters for all my languages?"

Before this RFC, using Turborepo across toolchains meant applying JavaScript conventions to other ecosystems. For example, you would have to add a package.json to each Python package for Turborepo to include it in the Package Graph. A more detailed description of this approach can be found in our multi-language support documentation (https://turborepo.dev/docs/guides/multi-language).

With this new experimental support, those workarounds are no longer necessary. Turborepo discovers uv workspace members naturally, adds their dependency relationships to the Package Graph, and maps common tasks to native uv commands.

Why uv?

uv has first-class support for Python projects and workspaces, including dependency resolution, lockfiles, environments, and package management. Turborepo builds on these existing conventions rather than introducing a separate workspace model.
uv is currently the only supported Python package manager.

What about standalone uv workspaces?

Standalone uv workspaces are supported. You do not need a JavaScript workspace or a root package.json for Turborepo to discover and run tasks for your Python packages.

Mixed-language repositories are also supported. A uv workspace can coexist with JavaScript and Cargo workspaces in the same Turborepo.

Enabling Python support

1. Use the first Turborepo canary containing Python support or higher.

• You are still required to use the npm ecosystem to install the turbo binary (https://turborepo.dev/docs/getting-started/installation).

2. Use a root uv workspace with a committed uv.lock.
3. Give the workspace a unique name in the root pyproject.toml:

[tool.turbo]
name = "my-python-workspace"

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

4. Enable the feature using its Future Flag in turbo.json:

{
  "futureFlags": {
    "experimentalPythonWorkspaces": true
  }
}

For more information on getting started, see the documentation linked at the beginning of this post.

Usage

Using Turborepo for Python should feel familiar if you have used it for JavaScript or TypeScript.

• Run turbo run build to build Python packages with uv build.
• Run turbo run format to format packages with uv format.
• Run turbo run check to type-check packages with uv check.
• Use --filter to target an individual Python package.
• Use turbo prune to produce a partial uv workspace.

For example:

turbo run build --filter=py-api
turbo run check
turbo run format

To learn more, see the documentation linked at the beginning of this post.

What feedback is the Turborepo team looking for?

In short, everything. We want to hear about:

• UX improvements
• Your experience in a standalone uv workspace
• Your experience in a mixed-language repository
• Task inference and filtering
• Caching behavior and concerns
• Pruning behavior
• Anything else?