Per-manager overrides¶

Each built-in manager exposes a small set of attributes that can be overridden from the configuration file. Add a [mpm.managers.<id>] section (or [tool.mpm.managers.<id>] in pyproject.toml) for each manager you want to tune. Values from the file take precedence over the built-in defaults and over the matching global [mpm] settings or --<flag> command-line values when both apply to the same field.

Overridable fields¶

Field	Type	Description
`cli_names`	list of strings	CLI binary names to look for, in order of priority.
`cli_search_path`	list of strings	Extra directories searched before `$PATH` for the binary.
`deprecated`	boolean	Mark a manager as deprecated, hiding it from default selection.
`dry_run`	boolean	Simulate CLI calls without performing any action, only for this manager.
`extra_env`	table of strings	Additional environment variables passed to every CLI call.
`ignore_auto_updates`	boolean	Exclude auto-updating packages from outdated/upgrade results, only for this manager.
`post_args`	list of strings	Arguments appended after every CLI invocation.
`pre_args`	list of strings	Arguments inserted before every CLI invocation.
`pre_cmds`	list of strings	Commands prepended to every CLI invocation (typically `sudo`).
`requirement`	string	PEP 440-style version requirement the manager must satisfy to be considered available.
`stop_on_error`	boolean	Stop on the first CLI error from this manager instead of continuing.
`sudo`	boolean	Run this manager’s privileged operations through `sudo` (overrides its built-in default: system managers escalate, user-level managers do not). See privilege escalation.
`timeout`	integer	Maximum duration in seconds for each CLI call from this manager.
`version_cli_options`	list of strings	CLI options used to extract the manager’s reported version.
`version_regexes`	list of strings	Regular expressions tried in order to extract the version from CLI output.

Important

List-valued fields use replace semantics: an override fully supersedes the built-in default rather than merging with it. For example, setting cli_search_path = ["/opt/bin"] on a manager that ships with cli_search_path = ("/usr/local/bin",) results in ("/opt/bin",), not the union of both.

Discover the override template¶

Run mpm config-template to print the current overridable attributes of every maintained manager as a ready-to-paste config block. Pass one or more manager IDs to narrow the output:

$ mpm config-template winget > my-overrides.toml
$ mpm config-template brew pip cargo

The output lists every overridable field with its current value, so it doubles as the canonical reference for what each manager exposes. Prune the rows that don’t apply and customize the rest. The output is valid TOML; redirect it directly into a config file or merge it into your existing [mpm] section.

Example: bypass a Windows app-store placeholder¶

Modern Windows ships placeholder executables under %LOCALAPPDATA%\Microsoft\WindowsApps\ that, when invoked, open the Microsoft Store rather than running the real CLI. If you have installed the genuine winget somewhere else, point cli_search_path at that directory so mpm finds it first:

[mpm.managers.winget]
cli_search_path = [
  "C:\\Program Files\\WindowsApps\\Microsoft.DesktopAppInstaller_1.27.0_x64",
]

The override directories are searched before $PATH, so the real binary wins over the store placeholder.

Example: relax a version requirement¶

A few managers gate themselves behind a minimum version. If you ship a custom build that reports an unconventional version string, override requirement:

[mpm.managers.guix]
requirement = ">=0.0"

Example: per-manager timeout and quiet mode¶

Slow managers can be given a longer timeout without affecting the rest of the pool. Combine with pre_args to silence chatty output:

[mpm.managers.brew]
timeout = 900

[mpm.managers.cargo]
pre_args = ["--quiet", "--color", "never"]

Validation¶

Unknown manager IDs and unknown field names are reported as warnings on <stderr> and skipped: a typo will not crash mpm. Type mismatches (a single string passed where a list is expected) raise an error so the offending value can be corrected.

Define a new manager¶

A [mpm.managers.<id>] section whose ID is not a built-in manager defines a brand-new manager rather than overriding one. mpm builds it at startup and treats it like any built-in: it gets its own --<id> / --no-<id> selectors, joins the default set on its supported platforms, and is driven by every subcommand it implements.

Important

A manager definition makes mpm run the commands you declare. Definitions are only loaded from a trusted, local configuration file (owned by you, not world-writable, never a remote --config URL). Read Security model before adding one.

Required keys¶

Key	Type	Description
`platforms`	list of strings	Platform or group IDs the manager runs on (like `linux`, `macos`, `all_platforms`, or a specific `ubuntu`).
`operations`	table	At least one operation (see below). A manager with no operations does nothing.

Every overridable field (cli_names, cli_search_path, requirement, version_regexes, pre_args, extra_env, timeout, …) may also be set, plus name and homepage_url. When cli_names is omitted it defaults to the manager ID.

Operations¶

Each entry under [mpm.managers.<id>.operations] declares one operation. Every operation takes an args list appended after the resolved binary.

Command operations run a CLI and need nothing else:

Operation	Required placeholder	Maps to
`install`	`{package_id}`	`mpm install`
`remove`	`{package_id}`	`mpm remove`
`upgrade_one`	`{package_id}`	single-package `mpm upgrade` (needs `installed` too)
`upgrade_all`	none	`mpm upgrade --all`
`sync`	none	`mpm sync`
`cleanup`	none	`mpm cleanup`

Query operations (installed, outdated, search) parse the command’s output. search also takes the {query} placeholder. Provide either a regex matched against each output line, or a JSON parser (format = "json" with a fields mapping and optional list_path). Both map these recognized fields to a package:

package_id (always required),
installed_version (required by installed),
latest_version (required by outdated).

Note

Version pinning is not expressible yet: install and upgrade on a config-defined manager always let the manager choose the version, and a {version} placeholder is not substituted. Native exact/extended search filtering is likewise not declarable, so mpm refilters search results itself.

Example¶

[mpm.managers.deno]
name = "Deno"
platforms = ["linux", "macos", "windows"]
homepage_url = "https://deno.land"
cli_names = ["deno"]
requirement = ">=1.40"
version_regexes = ['deno (?P<version>\S+)']

[mpm.managers.deno.operations.installed]
args = ["list"]
regex = '^(?P<package_id>\S+)@(?P<installed_version>\S+)$'

[mpm.managers.deno.operations.outdated]
args = ["outdated", "--json"]
format = "json"
list_path = "packages"
fields = { package_id = "name", installed_version = "current", latest_version = "latest" }

[mpm.managers.deno.operations.install]
args = ["install", "{package_id}"]

[mpm.managers.deno.operations.upgrade_one]
args = ["install", "--force", "{package_id}"]

After this, mpm --deno installed, mpm outdated, and mpm install jq --deno all work, and --deno appears in mpm --help.

Tip

A definition covers managers whose listings parse line-by-line or as a flat JSON array. When the real CLI needs multi-line records, pagination, or stateful parsing, the regex/JSON DSL is not enough: write a real manager and upstream it instead.

Help improve detection upstream¶

When an override targets a field that often points to an upstream detection bug, mpm prints a one-line invitation to file a bug report so the heuristics can be improved for everyone. The fields that trigger an invitation are: cli_names, cli_search_path, requirement, version_cli_options, and version_regexes. Overrides on preference fields like timeout or ignore_auto_updates never trigger an invitation.

The invitation is a pre-filled GitHub new-issue URL targeting the bug-report.yml template. Clicking it opens the bug-report form with the manager ID, field, override value, and what mpm detected without the override already filled in. The user only has to add the diagnostic command outputs the form requests (mpm --show-params, mpm --verbosity DEBUG --all-managers managers) before submitting.

To silence the invitation, pass --no-suggest-contribs on the command line, set the MPM_SUGGEST_CONTRIBS environment variable to false, or add to your config file:

[mpm]
suggest_contribs = false