Zsh Zim¶

ID: zim
Home page: https://zimfw.sh
Version requirement: >= 1
Platforms: 🐧 Linux · 🍎 macOS
Operations: installed · upgrade_all
purl types: pkg:zim
CLI name: zsh
Forced environment: NO_COLOR=1 · SHELL_SESSIONS_DISABLE=1
Issues and PRs: 📦 manager: zsh-based
Source: meta_package_manager/managers/zim.py

Zim is a configuration framework and module manager for Zsh.

Modules are declared in the user’s .zimrc, then cloned under $ZIM_HOME. Packages are identified by the module name Zim reports, which is the id mpm keys them on.

Caution

zimfw is a shell function, not a standalone binary: it is defined by sourcing $ZIM_HOME/init.zsh, and the zimfw.zsh script behind it carries no shebang. Every invocation is therefore wrapped in zsh -c. Zsh is the binary mpm executes, and Zim’s own presence is established by the version probe: a host with Zsh but no Zim fails to source and reports no version, which leaves the manager unavailable.

Caution

No install and no remove: Zim materializes exactly the module set the user’s own .zimrc declares. zimfw install fetches what that file already names and zimfw uninstall drops what it no longer names, so neither takes a module of mpm’s choosing. Installing one would mean mpm editing the user’s .zimrc, which is configuration mpm does not own. Both operations are therefore not implemented rather than faked, and mpm auto-skips them.

Note

No outdated: zimfw check does compare each module against its remote, but it reports through the same progress display as update rather than a parseable list, and no upstream sample pins its format down. upgrade --all still works and mpm auto-skips the operation.

Documentation: zimfw.

What `mpm` adds to `zim`¶

mpm reaches across every manager at once, not zim alone: mpm installed and mpm outdated cover zim alongside every other manager you run in one table, mpm upgrade --all updates them together, and mpm sbom exports the whole machine as one bill of materials.

Every mpm command also gains --dry-run and --plan previews, cross-scheme version comparison and purl identifiers. See manager augmentations for how each one is built.

Operations¶

Operation	Supported
`installed`	✓
`outdated`
`orphans`
`search`
`install`
`upgrade`
`upgrade_all`	✓
`remove`
`sync`
`cleanup`
`doctor`

Selecting and configuring `zim`¶

Deselect zim for a single run with --no-zim, or persist the choice in your configuration:

[mpm]
zim = false

The arguments and environment variables listed in the box atop this page are forced on every zim call, so runs stay quiet, non-interactive and reproducible: the defaults you would set in CI anyway.

Keep it enabled but tune how mpm drives it with a per-manager override:

[mpm.managers.zim]
timeout = 900

mpm config-template zim prints every overridable attribute as a ready-to-paste block.

Recipes¶

A few jobs you would otherwise script around zim, one mpm command each:

Snapshot and clone a machine: mpm --zim dump zim.toml, then mpm restore zim.toml on the next one.
Export a compliance SBOM: mpm --zim sbom (CycloneDX by default, --spdx for SPDX).

Privilege escalation¶

mpm runs this manager as the current user and never prepends sudo by default. Flip the policy for its privileged operations with --sudo or the per-manager sudo override.

See privilege escalation for the full policy.

Cooldown¶

State of Zsh Zim’s release-age gating, from the cooldown support table:

Status: ❌ None (clones a Git branch or tag, no release feed)

A cooldown only pays off where a compromised release can be withdrawn while the clock runs, and can only be emulated where the registry dates its releases. From the retraction table:

Registry: Upstream Git clones
Retraction: None: a plugin is cloned straight from its upstream repository, so withdrawing a bad revision is its author force-pushing, retagging or deleting it themselves. No index sits in between
Publish date: ❌ a commit or tag date is set by the author and freely rewritable

With --cooldown set, mpm skips this manager’s install and upgrade operations rather than run them unguarded (fail-closed); --allow-unsupported-managers opts back in.

Version probe¶

The version is probed by running:

$ zsh --version
1.18.0

and extracted with:

r"(?P<version>\d+(?:\.\d+)+)"

Reference traces¶

Raw native outputs captured in the manager source: the reference mpm’s parsers were written against. If you know Zsh Zim well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ zsh -c 'source ~/.zim/init.zsh && zimfw list'
environment
git
input
termtitle
utility
duration-info (frozen)
zsh-completions

Feed any of these through mpm and the raw output becomes one uniform table, the same shape for every manager: filter it, project columns, or export it (mpm --zim installed --output json, or csv, toml, yaml), each package carrying a purl and a version comparable across managers.

Changelog¶

7.7.0.dev0 (unreleased)
- Add the Zim Zsh module manager with installed and upgrade support. It declares no install or remove: Zim materializes only the module set the user’s own .zimrc names.