Packages
pkg names packages the way mise does, as manager:name, and records each one in your global mise config. This page covers the daily commands. The package contract in the repository has the full rules.
Name a package
Section titled “Name a package”| You see | You type | Where it is recorded |
|---|---|---|
brew install wget |
pkg install brew:wget |
[bootstrap.packages] |
brew install --cask iina |
pkg install brew-cask:iina |
[bootstrap.packages] |
brew install owner/tap/x |
pkg install brew:owner/tap/x |
[bootstrap.packages] |
| An App Store app | pkg install mas:<app id> |
[bootstrap.packages] |
npm install -g prettier |
pkg install npm:prettier |
[tools] |
| A tool in mise’s registry | pkg install ripgrep |
[tools] |
The prefix decides what kind of entry pkg makes:
- A prefix that names one of mise’s tool backends makes a tool in
[tools].npm,cargo,github,aqua,go, andpipxare backends;mise backends lslists all of them. - No prefix also makes a tool: a bare name such as
ripgrepcomes from mise’s registry, exactly asmise use ripgrepreads it. - Any other prefix is a bootstrap package manager, recorded in
[bootstrap.packages]:brew,brew-cask,mas,apt,dnf,flatpak,winget, and the others mise supports.
A package manager has to exist on the machine for mise to install with it. When you install a package whose manager this machine lacks, such as apt:curl on macOS, pkg records it in your config and does not install it. Another machine that has the manager installs it when it applies the config.
Homebrew keeps versions in its names (brew:postgresql@17), so there @ is part of the formula or cask name. For every other package, @<version> pins a version: node@24, apt:curl@8.5.0-2. A tool without a version is recorded as latest.
Find a package
Section titled “Find a package”pkg search looks through Homebrew’s formulae and casks, mise’s registry, and the App Store, and prints the exact package to pass to pkg install, its version, and whether your config already declares it.
pkg search ffmpeg # every sourcepkg search video player --manager brew-cask # casks only; several words need no quotespkg info brew:wget # one formula: description, homepage, version, dependenciespkg info mas:937984704 # one App Store appThe first search downloads Homebrew’s catalog, about 7 MB, and later searches download it again once the copy is a day old. Formulae in third-party taps are not in Homebrew’s catalog, so search does not find them. The repository’s catalog notes cover caching and what happens when a catalog is unreachable.
Install
Section titled “Install”Preview first, then install. You can name several packages from different sources in one command:
pkg install brew:wget brew-cask:iina --dry-runpkg install brew:wget brew-cask:iinapkg install ripgrep npm:prettierpkg handles each package in turn and reports what it did:
unchanged: already declared and installed. Installing twice is safe.installed: declared somewhere already but missing, so mise installs it where it is declared.added: not declared, so pkg records it in your config and mise installs it.declared: recorded, but not installed, because this machine lacks the package’s manager.
When mise fails, pkg takes the failed package’s new entry back out of your config and stops. The error names the packages installed before it, and a broken entry never stops a later mise bootstrap.
Third-party Homebrew taps
Section titled “Third-party Homebrew taps”mise finds a tap owner/name at https://github.com/owner/homebrew-name without any setup, so pkg install brew:owner/name/formula works directly. Only a tap whose repository lives at another GitHub URL needs its URL recorded first:
pkg tap add acme/tools https://github.com/acme/brew-tools.git --dry-runpkg tap add acme/tools https://github.com/acme/brew-tools.gitpkg install brew:acme/tools/<formula>pkg tap list shows the recorded URLs, and pkg tap remove acme/tools forgets one. Removing a tap leaves its packages declared and installed.
Remove
Section titled “Remove”pkg remove brew:wget --dry-runpkg remove brew:wgetmise has no command that uninstalls a single Homebrew package. Its mise bootstrap packages prune uninstalls every formula and cask that no config declares. So for a Homebrew package, pkg remove takes the entry out of your config, then prunes, and reports everything uninstalled, dependencies included.
Before it touches anything, pkg checks that the prune would remove only what you named. When other undeclared Homebrew packages are already installed, a prune would take them too, so pkg remove refuses with PRECONDITION_FAILED, lists them, and changes nothing. Then:
pkg prune --dry-run # see the undeclared packagespkg prune # uninstall thempkg install brew:jq # or keep one by declaring itOther kinds of package are removed differently:
- Tools are removed with
mise unuse, which also uninstalls versions no other config uses. - mise cannot uninstall App Store apps or other managers’ packages. pkg takes them out of your config and lists them under
leftInstalledfor you to delete. - A formula that a declared package still depends on stays installed and is listed under
leftInstalled. - A package declared in a config file pkg does not edit fails with
PRECONDITION_FAILEDand names the file. Configuration explains why.
Keep packages up to date
Section titled “Keep packages up to date”pkg outdated # what has a newer version, mise firstpkg update --dry-run # what an update would changepkg update # mise itself, then everything elsepkg update brew:wget # only the packages you namepkg outdated compares Homebrew formulae and casks, App Store apps, global tools, and mise itself against their newest versions. Casks mise will not update, such as apps that update themselves, appear under skipped, and so does a newer mise that a package manager installed.
pkg update lists each version that changed. With no names, it first runs mise self-update, so packages and tools then update with the new mise. If that step fails, pkg stops before changing anything else. A mise installed by Homebrew, apt, or another package manager refuses to update itself, so pkg leaves it to that package manager and lists it under skipped. mise also waits until a release has reached its minimum release age, a day unless you set minimum_release_age, so pkg outdated can list a mise release that pkg update leaves for later.
Once pkg is handed to mise, pkg update updates pkg too. A package that is declared but not installed is left to pkg sync.
Find where something is installed
Section titled “Find where something is installed”pkg where brew:wget # the formula's opt directorypkg where jq # a tool's install directoryKeg-only formulae need their opt directory on your PATH by hand, and pkg where prints it. Casks, App Store apps, and other managers’ packages have no such directory.
Preview with dry run
Section titled “Preview with dry run”--dry-run works on every command that changes something: install, remove, update, sync, prune, tap add, tap remove, setup, and bootstrap. A dry run makes the same checks and decisions as the real run, including refusals, and installs, uninstalls, and writes nothing. With --output json, its receipt has status set to dry-run. A bootstrap preview has limits of its own, because a configuration can run commands.