docs/tasks/monorepo.md
mise supports monorepo-style task organization with target path syntax. This lets you manage tasks across multiple projects in a single repository, where each project can have its own mise.toml with tools, environment variables, and tasks that differ from those of the directory the task is called from.
Set monorepo_root = true and list project directories in
[monorepo].config_roots. mise loads their tasks into a shared namespace, with
each task prefixed by its path relative to the monorepo root. Configuration roots
and the experimental workspace project graph
are separate: the former locate task configuration; the latter infer relationships
from package metadata.
::: tip
The directory containing a mise.toml file is called the config_root. In monorepo mode, each project can have its own config_root with its own configuration, separate from the monorepo root. If you use one of the alternate paths in a subdirectory, such as ./projects/frontend/.mise/config.toml, the config_root is ./projects/frontend, not ./projects/frontend/.mise.
:::
Declare the root and its project directories in the repository's mise.toml:
# /myproject/mise.toml
monorepo_root = true
[monorepo]
config_roots = ["projects/frontend", "projects/backend"]
[tools]
# Tools defined here apply to all subdirectories
node = "20"
myproject/
├── mise.toml (with monorepo_root = true)
├── projects/
│ ├── frontend/
│ │ └── mise.toml (with tasks: build, test)
│ └── backend/
│ └── mise.toml (with tasks: build, test)
With this structure, tasks are automatically namespaced:
//projects/frontend:build//projects/frontend:test//projects/backend:build//projects/backend:testMonorepo tasks use special path syntax with // and : prefixes. You can run these tasks directly with mise or with mise run. For non-monorepo tasks, the guidance is to avoid the direct syntax in scripts because a task name could conflict with a future core mise command. mise will never define commands with a // or : prefix, however, so this guidance does not apply to monorepo tasks.
# Direct syntax (preferred for monorepo tasks)
mise //projects/frontend:build
# Also works with 'run'
mise run //projects/frontend:build
# Need quotes for wildcards
mise '//projects/frontend:*'
Use the // prefix to specify an absolute path from the monorepo root:
# Run build task in frontend project
mise //projects/frontend:build
# Run test task in backend project
mise //projects/backend:test
Use the : prefix to run tasks in the current config_root:
cd projects/frontend
mise :build # Runs the build task from frontend's config_root
This works from any directory below a config_root, not just the config_root itself. The
task name resolves to the nearest enclosing config_root, so cd projects/frontend/src/components && mise :build also runs frontend's build. If no config_root encloses the current directory,
the name resolves against the monorepo root.
::: tip Optional Colon Syntax
The leading : is optional when running tasks from subdirectories or defining task dependencies. While both syntaxes work, we encourage using the : prefix to be explicit about monorepo task references.
Running from subdirectory:
cd projects/frontend
mise :build # Recommended: Explicit monorepo task reference
mise build # Also works (for migration compatibility)
Task dependencies:
# projects/frontend/mise.toml
[tasks.lint]
run = "eslint ."
[tasks.build]
depends = [":lint"] # Explicit reference to this config root
# Alternatively, replace the line above with: depends = ["lint"]
run = "webpack build"
Dependency paths beginning with ./ are resolved relative to the task that
declares them. This makes it possible to reuse the same dependency declaration
at different levels of a monorepo:
[tasks.test]
depends = [{ task = "./...:groups:tests:*", optional = true }]
For example, when declared by //apps/frontend:test, this pattern resolves to
//apps/frontend/...:groups:tests:* and matches the current project and its
descendants without matching sibling projects.
The bare-name syntax (without :) is supported primarily to ease migration from non-monorepo to monorepo configurations: existing task dependencies keep working, so you don't need to update them all at once. The : prefix, however, makes it clear that you're referencing a task in the current config_root.
:::
mise supports two types of wildcards for flexible task execution:
...)Use an ellipsis (...) to match any directory depth:
# Run 'test' task in ALL projects (any depth)
mise //...:test
# Run 'build' in all subdirs under projects/
mise //projects/...:build
# Match paths with wildcards in the middle
mise //projects/.../api:build # Matches projects/*/api and projects/*/*/api
::: info
Additional glob patterns may be added in a future version, so mise //projects/*:build
and mise '//projects/**:build' will likely be supported. We're using ... because it matches
how Bazel and Buck2 do it.
:::
*)Use an asterisk (*) to match task names:
# Run ALL tasks in frontend project
mise '//projects/frontend:*'
# Run all tasks starting with 'test:'
mise '//projects/frontend:test:*'
# Run 'lint' task across all projects
mise //...:lint
You can combine both types of wildcards for powerful patterns:
# Run all tasks in all projects (idk why you'd ever want to do this, but you can)
mise '//...:*'
# Run test and nested test groups in all projects
mise run '//...:test' ::: '//...:test:**'
# Run build tasks in all frontend-related projects
mise //.../frontend:build
Subdirectory tasks automatically use tools and environment variables from parent config files in the hierarchy. However, each subdirectory can also define its own tools and environment variables in its config_root. This lets you:
vars follow the same hierarchy for task templating, so child config vars are available when
running subdirectory tasks from the monorepo root.
Task templates like <span v-pre>sources = ["{{env.SRC_DIR}}/*"]</span> are rendered with env from the
task's own config hierarchy, so a subproject's [env] section applies no matter where the task
is invoked from.
Child task_config.includes templates can also reference inherited vars, which is useful for
centralized task includes like <span v-pre>git::https://example.com/tasks.git//go.toml?ref={{vars.central_ref}}</span>.
# /myproject/mise.toml
monorepo_root = true
[tools]
node = "20" # Available to all subdirectories
python = "3.12" # Available to all subdirectories
[env]
LOG_LEVEL = "info" # Available to all subdirectories
# /myproject/projects/frontend/mise.toml
[tools]
node = "18" # Overrides the root's node 20
[env]
LOG_LEVEL = "debug" # Overrides the root's LOG_LEVEL
PORT = "3000" # Adds new environment variable
[tasks.build]
run = "npm run build" # Uses node 18 and LOG_LEVEL=debug
# /myproject/projects/backend/mise.toml
# No tools or env section - uses node 20, python 3.12, and LOG_LEVEL=info from root
[tasks.build]
run = "npm run build" # Uses node 20 and LOG_LEVEL=info from root
tools and env properties take highest precedenceUse mise install --monorepo to install the union of tools from every directory listed in [monorepo].config_roots. This is useful in CI when you want to warm a cache for all projects in the repository:
MISE_ENV=ci mise install --monorepo
Passing a tool name filters the union while preserving multiple configured versions:
mise install --monorepo node
mise ls --monorepo lists the same union and can be used to inspect cache keys or debug which config roots are contributing tools. Both commands require monorepo_root = true and explicit [monorepo].config_roots.
Monorepos can use one lockfile at the monorepo root. Tools from packages/api/mise.toml write to <monorepo_root>/mise.lock, while environment and local variants write to root files such as mise.ci.lock and mise.local.lock.
This is rolling out as a tri-state setting. During the rollout window, leaving it unset keeps today's per-subproject lockfile behavior. Set lockfile = true to opt into root lockfiles now:
[monorepo]
lockfile = true
If mise finds old subproject lockfiles, it migrates them into the root lockfile the next time a lock-aware command runs. Root entries win on conflicts, unique subproject entries are preserved, and migrated subproject lockfiles are removed.
To keep lockfiles next to each subproject config after the default changes, pin the old behavior in the monorepo root:
[monorepo]
lockfile = false
Monorepos that leave the setting unset and use mise*.lock files will start warning in mise 2026.12.0 and will default to root lockfiles in mise 2027.6.0. Older mise versions do not understand unified monorepo lockfiles for subproject-owned tools. Teams that need mixed-version compatibility should use lockfile = false until everyone has upgraded.
You must explicitly list your config roots using the [monorepo] section:
# /myproject/mise.toml
monorepo_root = true
[monorepo]
config_roots = [
"packages/frontend",
"packages/backend",
"services/*", # Single-level glob pattern
]
This tells mise exactly which directories contain project configurations. Benefits:
* for single-level patterns (e.g., services/* matches services/api, services/worker)::: tip
Single-level globs (*) are supported, but recursive globs (**) are not. This keeps performance predictable while still allowing flexible patterns.
:::
::: warning Automatic Discovery Deprecated
Automatic filesystem walking to discover monorepo subdirectories is deprecated. If you don't define [monorepo].config_roots, mise still walks the filesystem for task discovery but emits a deprecation warning; mise install --monorepo and mise ls --monorepo do not fall back and always require explicit config roots. Migrate to explicit config roots.
:::
When more than one config in the hierarchy sets monorepo_root = true, the nearest one wins. This comes up with git worktrees checked out inside the main checkout:
myproject/mise.toml # monorepo_root = true
myproject/packages/api/mise.toml
myproject/.worktrees/feature-x/mise.toml # monorepo_root = true (same repo, other branch)
myproject/.worktrees/feature-x/packages/api/mise.toml
From inside myproject/.worktrees/feature-x, that directory is the monorepo root: //packages/api:build resolves to the worktree's copy, {{config_root}} points inside the worktree, and the worktree's own [monorepo].config_roots are the ones expanded.
Tasks from the enclosing monorepo are not loaded. They belong to a different monorepo's task set rather than to a parent namespace of the selected root, so loading them would place them outside the // namespace — you'd see build from the main checkout sitting next to //:build from the worktree. Everything above the enclosing root (your global config, a $HOME/mise.toml) is unaffected and still contributes tasks as usual.
The enclosing config is still an ancestor config for tools, environment variables, and vars, which inherit the same way any parent config's would. If you don't want that either, keep worktrees outside the main checkout (e.g. myproject-worktrees/feature-x).
mise can infer a provider-neutral project graph from ecosystem workspace metadata. This graph is separate from config-root task discovery: a project does not need its own mise.toml to appear in the graph.
Enable experimental features and mark the repository root:
# /myproject/mise.toml
monorepo_root = true
[settings]
experimental = true
Inspect the inferred projects with:
mise tasks graph
mise tasks graph --explain
mise tasks graph --json
Use --explain to see which workspace provider inferred each project, dependency edge, and task.
When a provider suggests task inputs, outputs, cacheability, or dependencies, the explanation also
shows the provider and ecosystem metadata file for each suggested field. Values introduced by
[monorepo.projects] overrides are labeled configuration instead of being attributed to a
provider.
The JSON output includes the same information in each project's provenance,
dependency_provenance, and tasks fields. Task suggestions contain field-level provenance so
other tooling can distinguish, for example, a turbo.json output declaration from a root mise task
default.
Use mise run --affected <task-pattern> to run a task only in projects changed between two Git
revisions. mise selects projects that own changed paths, then follows reverse project dependencies
so downstream projects are included. Workspace-global paths and task_config.global_inputs select
the whole workspace. Providers may narrow lockfile changes to the projects whose external
dependencies changed.
# Compare HEAD to its first parent and run affected build tasks
mise run --affected build
# Inspect the selection while preserving normal dry-run behavior
mise run --affected --affected-explain --dry-run build
# Emit the selection as JSON without running tasks
mise run --affected --affected-json build
# Compare explicit revisions
mise run --affected --affected-base origin/main --affected-head HEAD test
--affected-explain lists each selected project and its cause: an owned changed path, a
workspace-global path, a provider-attributed lockfile, or a dependency on another affected project.
It also lists the task-pattern matches associated with those projects. Normal task dependencies are
expanded afterward, so a selected task can still run a required prerequisite from an unchanged
project.
--affected-json emits the same pre-expansion selection without running tasks. Its stable JSON
object contains the base and head revisions, affected projects with their roots and reasons, and
task-pattern matches with their associated project IDs.
The revision defaults are HEAD~1 and HEAD locally. MISE_AFFECTED_BASE and
MISE_AFFECTED_HEAD override them. GitHub Actions and GitLab merge-request metadata provide CI
defaults when those variables are not set; explicit CLI options take highest precedence.
The Cargo provider discovers packages when the root Cargo.toml contains a [workspace] table.
It expands the workspace's members patterns, honors exclude, and includes the root package when
the workspace manifest also contains [package]. Path dependencies inside the workspace root are
included as implicit members, matching Cargo's workspace membership behavior. A path outside the
workspace remains an external dependency and is not added to the graph.
Each discovered package must have a [package].name. mise uses that stable ecosystem identity to
create an ID such as cargo:my-crate; moving the crate to another directory does not change its ID.
mise tasks graph also reports the package root and Cargo.toml as the workspace-definition source.
Discovery parses manifests directly and does not require the cargo executable to be installed.
For every discovered Cargo package, mise infers internal edges from dependencies with a local
path. Normal, development, build, and target-specific dependency tables all participate. Renamed
dependencies are resolved by their path, and declarations with workspace = true inherit paths
from the root [workspace.dependencies] table.
Version-only and registry dependencies are ignored, as are path dependencies outside the workspace
or beneath an excluded path. Declarations that resolve back to the same package do not create a
self-edge. If the inferred internal edges produce a cycle, mise tasks graph reports the cycle;
project overrides can replace or adjust the inferred dependencies when needed.
The uv provider discovers Python projects when the root pyproject.toml contains a
[tool.uv.workspace] table. The root project is always included, and mise expands members globs
and honors exclude for the remaining workspace members. Each project must define
[project].name; mise normalizes equivalent Python package spellings such as my_package,
my.package, and my-package to a stable ID such as uv:my-package.
Local directory sources under the configured monorepo root are also represented as projects, even
when they are excluded from uv workspace membership. This preserves dependency edges for uv's
path-dependency alternative to workspaces. Local metadata is parsed directly, so neither uv nor
Python needs to be installed for graph discovery.
mise reads dependencies from [project].dependencies, optional dependency groups,
[dependency-groups], and uv's legacy dev-dependencies. An internal edge is added only when the
corresponding [tool.uv.sources] entry selects a workspace member with workspace = true or points
to an in-repository project directory with path. Root source declarations apply to workspace
members unless a member overrides that dependency's source.
Source arrays with environment markers are treated conservatively: any local alternative adds the
edge because the graph is platform-independent. Registry, Git, URL, wheel, source archive, and
external-workspace sources do not add projects or edges. Self-dependencies are ignored, while
cycles among projects are reported by mise tasks graph and can be corrected with project
overrides.
The Go provider discovers modules listed by use directives in the root go.work. Both individual
directives and use blocks are supported. Each listed directory must contain a go.mod with a
module directive; mise uses that stable module path to create an ID such as
go:example.com/acme/api. Modules listed outside the configured monorepo root are ignored because
project roots in the mise graph are always repository-relative.
Discovery parses go.work and go.mod directly and does not require the go executable. It does
not infer dependency edges from require or replace: those directives describe module selection,
not necessarily the source-level relationship needed by a task graph. Add the edges that matter to
your build with project overrides:
[monorepo.projects."go:example.com/acme/api"]
depends_add = ["go:example.com/acme/lib"]
Use depends to replace the complete dependency set, or depends_add and depends_remove for
targeted adjustments. The graph explanation attributes these configured edges to configuration.
The Node provider discovers npm, pnpm, Yarn, and Bun workspace packages from:
pnpm-workspace.yamlworkspaces array in the root package.jsonworkspacesworkspaces.packagesWhen both files exist, pnpm-workspace.yaml defines membership. For pnpm and detected Yarn workspaces, a valid root package.json with a name is implicitly included. Positive and negative patterns, recursive ** globs, and brace patterns such as packages/{web,api} are supported for Node workspace discovery. Discovery skips .git and node_modules, but does not apply Git ignore files or .ignore files.
Each discovered package must have a name in its package.json. mise uses that stable ecosystem identity to create an ID such as node:@acme/web; moving the package to another directory does not change its ID. mise tasks graph also reports the package root, workspace-definition source, and detected package manager.
For every discovered Node package, mise checks these package.json fields:
dependenciesdevDependenciesoptionalDependenciespeerDependenciesWhen a declared dependency name exactly matches another discovered workspace package, mise adds an edge to that package's stable node: project ID. External package names and declarations that refer back to the same project are ignored.
Dependency version strings are treated as opaque. A matching internal name creates the same edge whether its value uses workspace:*, catalog:, *, a normal version range, or another package-manager-specific form. mise does not resolve or compare those values when constructing the project graph.
All four dependency kinds participate in the same project graph, including development dependencies. If the declarations produce a cycle, mise tasks graph reports the cycle instead of silently dropping an edge. Use depends, depends_add, or depends_remove in a project override when the inferred build relationship needs to differ from the package manifests.
When task inference and experimental features are enabled, mise imports scripts from each
discovered Node workspace package as tasks. Packages do not need their own mise.toml.
An imported task uses the stable project ID followed by # and the package script name:
mise run 'node:@acme/web#build'
The equivalent monorepo path is available as an alias, so existing path patterns also work:
mise run //apps/web:build
mise //...:test
The task runs in the package directory through the workspace package manager (npm, pnpm,
yarn, or bun) and passes task arguments through to it. mise uses the root packageManager
declaration or lockfile to select the manager and falls back to npm when neither identifies one.
mise task info reports the package's package.json as the task source.
An explicit mise task at the package's monorepo path takes precedence over the imported script. Both names continue to resolve to that explicit task.
This inference is opt-in, currently experimental, and only runs for a configured monorepo root:
[settings]
experimental = true
task.auto_infer = ["node"]
Use [monorepo.task_defaults.<name>] in the root mise.toml to define shared defaults for
tasks with the same name in every workspace project:
[monorepo.task_defaults.build]
sources = ["src/**", "package.json"]
outputs = ["dist/**"]
cache = { enabled = true }
[monorepo.task_defaults.test]
env = { NODE_ENV = "test" }
These defaults apply to both provider-inferred tasks such as node:@acme/web#build and explicit
mise tasks such as //apps/web:build. Task-local configuration takes precedence. When an explicit
task uses extends, its template also takes precedence over the root default.
Root task defaults are experimental and are ignored unless experimental features are enabled.
Task definitions are resolved in two stages. First, an explicit project task replaces a provider-inferred task with the same project and task name. The provider task's project-ID name is kept as an alias for the explicit task, so either name runs the explicit definition.
After selecting the task, mise fills unset fields in this order, from highest to lowest precedence:
extends, for explicit tasks that use one[monorepo.task_defaults.<name>] definition from the workspace rootMap fields such as env, vars, and tools merge across these layers, with entries from the
higher-precedence layer winning. Collection fields such as depends, sources, and outputs use
the complete value from the highest-precedence layer that defines them rather than concatenating
values from multiple layers. These are the same merge rules used by task templates.
For example, an inferred package script keeps its provider command when the root default also
defines run, while still inheriting cache inputs or environment entries that the provider did not
specify. If a project later defines that task explicitly, the explicit command replaces the package
script; a named template fills its missing fields before the root default does.
Workspace providers can attach task configuration when ecosystem metadata describes it unambiguously. A provider can suggest:
sources^task dependenciesSuggestions are part of the inferred task definition, so they have the same precedence as the provider command. A matching explicit project task replaces them. Otherwise, task templates and root task defaults fill only fields the provider did not suggest. Providers leave fields unset when their ecosystem metadata is not authoritative; mise does not guess outputs or cacheability from a command string.
The Node workspace provider reads inputs, outputs, cache, and dependsOn from matching
turbo.json task definitions. Turbo-specific patterns that mise cannot preserve exactly, such as
$TURBO_ROOT$, are left unset so a task template or root task default can supply them instead.
Prefix a task dependency with ^ to run that task in upstream workspace projects first. A root
task default is the usual way to apply this relationship across the workspace:
[monorepo.task_defaults.build]
depends = ["^build"]
The ^ prefix is supported only in depends. It is rejected in depends_post and wait_for
because those fields do not describe prerequisite work.
Running node:@acme/web#build now runs build in each project that @acme/web depends on before
building @acme/web. The relationship follows the complete project dependency graph, including
through intermediate projects that do not define build. Missing upstream tasks are skipped.
For a configured task root that is not represented in the detected project graph, the dependency
is a no-op because that task has no upstream project relationship.
Upstream dependencies work with both provider-inferred tasks and explicit mise tasks. They use the
same task scheduler as ordinary depends, including cycle detection, deduplication, parallel
execution, and dependency cache-key propagation. This syntax is available only for configured
monorepo workspaces while experimental features are enabled.
Use [monorepo.projects] in the root mise.toml to correct or extend provider inference. Project IDs containing : or scoped package names must be quoted:
[monorepo.projects."node:@acme/web"]
root = "apps/web"
depends_add = ["custom:docs"]
depends_remove = ["node:@acme/legacy"]
[monorepo.projects."custom:docs"]
root = "docs"
metadata = { kind = "documentation" }
An override can:
remove = true to remove an inferred project and its connected edgesroot or metadata to replace inferred valuesdepends to replace the complete inferred dependency setdepends_add and depends_remove to adjust individual edgesrootThe final graph must reference existing project IDs and must not contain dependency cycles. Diagnostics identify the affected projects and the override fields that can repair the graph.
The difference between mise tasks and mise tasks --all:
mise tasks: Lists tasks from the current config_root hierarchy (current config_root and its parents)mise tasks --all: Lists tasks from the entire monorepo, including sibling and descendant directoriesGiven this structure:
myproject/
├── mise.toml (task: deploy)
├── projects/
│ ├── frontend/
│ │ └── mise.toml (tasks: build, test)
│ └── backend/
│ └── mise.toml (tasks: build, serve)
When in projects/frontend/:
# Lists: //:deploy, //projects/frontend:build, //projects/frontend:test
mise tasks
# Lists: //:deploy, //projects/frontend:build, //projects/frontend:test,
# //projects/backend:build, //projects/backend:serve
mise tasks --all
# List all tasks in frontend project
mise tasks '//projects/frontend:*'
Place commonly used tools and environment in the root mise.toml to avoid repetition:
# /myproject/mise.toml
monorepo_root = true
[tools]
node = "20"
python = "3.12"
go = "1.21"
[env]
NODE_ENV = "development"
Only override tools in subdirectories when they genuinely need different versions:
# /myproject/legacy-app/mise.toml
[tools]
node = "14" # Override only for legacy app
# python and go from root
Prefix related tasks with common names to enable pattern matching:
[tasks.test]
run = "npm test"
[tasks."test:unit"]
run = "npm run test:unit"
[tasks."test:e2e"]
run = "npm run test:e2e"
Then run the named test task and nested test groups:
mise run '//...:test' ::: '//...:test:**'.
Organize projects in subdirectories to enable targeted execution:
myproject/
├── services/
│ ├── api/
│ ├── worker/
│ └── scheduler/
└── apps/
├── web/
└── mobile/
Then run tasks by group:
mise //services/...:build # Build all services
mise //apps/...:test # Test all apps
Choose mise when you want project-specific tools, environment variables, and task commands in the same configuration. Existing package scripts and build systems can remain responsible for compilation; a mise task invokes them with the selected environment.
Decide which layer owns each behavior before combining task runners:
The following Python example assumes a uv project with pytest and pytest-cov
in its development dependencies.
For monorepos with similar task patterns across projects, task templates let you define reusable task definitions at the monorepo root:
# Root mise.toml
monorepo_root = true
[monorepo]
config_roots = ["packages/api"]
[task_templates."python:build"]
run = "uv build"
tools = { python = "3.12", uv = "latest" }
[task_templates."python:test"]
run = "uv run pytest"
tools = { python = "3.12", uv = "latest" }
depends = ["build"]
Projects can then extend these templates:
# packages/api/mise.toml
[tasks.build]
extends = "python:build"
[tasks.test]
extends = "python:test"
run = "uv run pytest --cov" # Override with coverage
See Task Templates for complete documentation.