Configuration¶

All mpm options can be set with a configuration file.

Location¶

Configuration is auto-discovered from two places, in order of priority:

pyproject.toml: searched from the current working directory upward to the nearest VCS root (.git, .hg, etc.), using a [tool.mpm] section. This follows the same discovery pattern as uv, ruff, and mypy.
Dedicated config file: searched in the platform-specific application directory.

Platform	Folder
macOS	`~/Library/Application Support/mpm/`
Unix	`~/.config/mpm/`
Windows	`C:\Users\<user>\AppData\Roaming\mpm\`

The dedicated config file can be TOML, YAML, JSON, or any format supported by click-extra (install extra dependencies for additional format support). An explicit --config flag always takes precedence over auto-discovery.

File format¶

Standalone TOML¶

A typical ~/.config/mpm/config.toml:

[mpm]
verbosity = "INFO"
timeout = 300
flatpak = true
pipx = true

[mpm.search]
exact = true

`pyproject.toml`¶

The same configuration embedded in a project’s pyproject.toml:

[tool.mpm]
timeout = 300
pip = false

[tool.mpm.search]
exact = true

The [tool.mpm] section maps directly to [mpm] in a standalone config file. The [tool] prefix is stripped automatically.

Available options¶

Every CLI option on the root mpm group and its subcommands can be set in the configuration file. The TOML key is the option name with leading dashes removed and remaining dashes replaced by underscores (or kept as-is for manager IDs like apt-mint).

Global options¶

These go under [mpm] (or [tool.mpm] in pyproject.toml):

Key	Type	Default	Description
`verbosity`	string	`"INFO"`	Logging level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, or `DEBUG`.
`timeout`	integer	`500`	Maximum duration in seconds for each manager CLI call.
`ignore_auto_updates`	boolean	`true`	Exclude auto-updating packages from outdated/upgrade results.
`stop_on_error`	boolean	`false`	Stop on first manager CLI error instead of continuing.
`dry_run`	boolean	`false`	Simulate CLI calls without performing any action.
`all_managers`	boolean	`false`	Force evaluation of all managers, including unsupported and deprecated.
`description`	boolean	`false`	Show package description in results.
`sort_by`	string	`"manager_id"`	Sort results by: `manager_id`, `manager_name`, `package_id`, `package_name`, or `version`.
`stats`	boolean	`true`	Print per-manager package statistics.
`table_format`	string	`"rounded-outline"`	Table rendering style (see `mpm --help` for all choices).

Subcommand options¶

These go under [mpm.<subcommand>] (or [tool.mpm.<subcommand>]):

[mpm.search]

Key	Type	Default	Description
`exact`	boolean	`false`	Only return exact matches instead of fuzzy search.
`extended`	boolean	`false`	Extend search to description and other package attributes.
`refilter`	boolean	`true`	Re-filter results locally when the manager’s search is too loose.

[mpm.installed]

Key	Type	Default	Description
`duplicates`	boolean	`false`	Only list packages installed by more than one manager.

[mpm.outdated]

Key	Type	Default	Description
`plugin_output`	boolean	`false`	Render output for Xbar/SwiftBar plugin consumption.

[mpm.upgrade]

Key	Type	Default	Description
`all`	boolean	`false`	Upgrade all outdated packages (not just those specified).

[mpm.backup]

Key	Type	Default	Description
`overwrite`	boolean	`false`	Allow overwriting an existing backup file.
`merge`	boolean	`false`	Merge new packages into an existing backup file.
`update_version`	boolean	`false`	Update version of packages already in the backup file.

[mpm.sbom]

Key	Type	Default	Description
`spdx`	boolean	`true`	Use SPDX format (`false` for CycloneDX).
`overwrite`	boolean	`false`	Allow overwriting an existing SBOM file.

Full example¶

# ~/.config/mpm/config.toml

[mpm]
# Only consider Homebrew and Pip by default.
brew = true
pip = true

# Increase timeout for slow connections.
timeout = 600

# Always show package descriptions.
description = true

# Sort by package name instead of manager.
sort_by = "package_name"

# Output as JSON for scripting.
table_format = "json"

[mpm.search]
# Use exact matching.
exact = true

[mpm.backup]
# Merge into existing backup files by default.
merge = true

Selecting managers¶

Default managers¶

You can select which package managers mpm considers by default. Setting a manager to true restricts mpm to that manager:

[mpm]
flatpak = true
pipx = true

This is equivalent to always passing --flatpak --pipx on the command line.

$ mpm managers
info: User selection of managers by priority: > flatpak > pipx
info: Managers dropped by user: None
╭────────────┬─────────┬────────────────────┬──────────────────────────┬────────────┬─────────╮
│ Manager ID │ Name    │ Supported          │ CLI                      │ Executable │ Version │
├────────────┼─────────┼────────────────────┼──────────────────────────┼────────────┼─────────┤
│ flatpak    │ Flatpak │ ✘ BSD, Linux, Unix │ ✘ flatpak not found      │            │         │
│ pipx       │ Pipx    │ ✓                  │ ✓ /opt/homebrew/bin/pipx │ ✓          │ ✓ 1.7.1 │
╰────────────┴─────────┴────────────────────┴──────────────────────────┴────────────┴─────────╯

Hint

There is an alternative syntax to specify default managers, which is to use the manager key:

[mpm]
manager = ["flatpak", "pipx"]

It calls mpm with the --manager flatpak and --manager pipx parameters instead of --flatpak and --pipx.

It is equivalent to the previous example, but call the hidden --manager parameter. This parameter is not shown in the help message as it is less user-friendly.

You can still mix both syntax in the same configuration file, as well as on the command line.

Ignore a manager¶

Setting a manager to false excludes it. This user wanted mpm to always ignore pip to speed up execution:

[mpm]
pip = false

Hint

There is an alternative syntax to ignore managers:

[mpm]
exclude = ["pip", "pipx"]

It calls mpm with the --exclude pip and --exclude pipx parameters, which is the equivalent of --no-pip and --no-pipx options.

The --exclude parameter is advertised in the help message as it is less user-friendly than single --no-<manager> flags.

You can still mix both syntax in the same configuration file, as well as on the command line.

Overlapping managers¶

mpm supports some overlapping package managers. Take for instance pacman and its collection of AUR helpers like paru and yay. All of these alternatives have the same source of packages as pacman. So updates to a single package may show up multiple times, because AUR helpers depends on pacman (which is always installed on the system).

You can fine-tune this behaviour by simply excluding redundant managers depending on your preferences.

For instance, if yay is your preferred helper and pacman and paru are polluting your entries, you can setup a configuration file in ~/.config/mpm/config.toml to exclude the other AUR helpers by default:

[mpm]
pacman = false
paru = false

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.
`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 dump-toml 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 dump-toml winget > my-overrides.toml
$ mpm dump-toml 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 (e.g. passing a single string where a list is expected) raise an error so the offending value can be corrected.

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

Precedence¶

Options are resolved in this order, from highest to lowest priority:

Command-line flags (--timeout 300).
Environment variables (MPM_TIMEOUT=300).
Configuration file values.
Built-in defaults.

Validation¶

Use --validate-config to check a configuration file for errors without running a command:

$ mpm --validate-config ~/.config/mpm/config.toml
Configuration file /home/user/.config/mpm/config.toml is valid.

This validates option names against the CLI parameters and reports unknown keys.

Troubleshooting¶

You can easily debug the way mpm sources its configuration with --show-params:

Configuration¶

Location¶

File format¶

Standalone TOML¶

pyproject.toml¶

Available options¶

Global options¶

Subcommand options¶

Full example¶

Selecting managers¶

Default managers¶

Ignore a manager¶

Overlapping managers¶

Per-manager overrides¶

Overridable fields¶

Discover the override template¶

Example: bypass a Windows app-store placeholder¶

Example: relax a version requirement¶

Example: per-manager timeout and quiet mode¶

Validation¶

Help improve detection upstream¶

Precedence¶

Validation¶

Troubleshooting¶

`pyproject.toml`¶