FreeBSD pkg¶

ID: pkg
Links: Documentation · Repository · Wikipedia
Upstream stars: ⭐ 827
Last commit: 2026-09-28
Version requirement: >= 1.11
Platforms: 🅱️ BSD (FreeBSD only)
Operations: installed · outdated · orphans · search · install · upgrade · upgrade_all · remove · sync · cleanup · doctor
purl types: pkg:pkg/
CLI name: pkg
Issues and PRs: 📦 manager: pkg-based
Source: pkg.py

FreeBSD’s binary pkg frontend, fetching pre-compiled artifacts from the official FreeBSD repository.

Only root may modify the package database, so mutating operations escalate through sudo by default, like the Ports sibling.

What `mpm` adds to `pkg`¶

mpm reaches across every manager at once, not pkg alone: mpm installed and mpm outdated cover pkg 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.

Your `pkg` commands, in `mpm`¶

You already know pkg: each operation maps one-to-one onto mpm, in an interface shared by every manager.

To…	With `pkg`	With `mpm`
List what’s installed	`pkg query "%n %v %c"`	`mpm --pkg installed`
List outdated packages	`pkg upgrade --quiet --dry-run`	`mpm --pkg outdated`
Install a package	`sudo pkg install --quiet --yes dmg2img`	`mpm install pkg:pkg/dmg2img`
Upgrade one package	`sudo pkg upgrade --quiet --yes dmg2img`	`mpm --pkg upgrade dmg2img`
Upgrade everything	`sudo pkg upgrade --quiet --yes`	`mpm --pkg upgrade --all`
Remove a package	`sudo pkg delete --quiet --yes dmg2img`	`mpm remove pkg:pkg/dmg2img`
List orphaned dependencies	`pkg autoremove --quiet --dry-run`	`mpm --pkg orphans`
Clear caches	`sudo pkg clean --quiet --yes --all`	`mpm --pkg cleanup --cache`
Run health checks	`pkg check --checksums --all`	`mpm --pkg doctor`

Prefix any command above with --dry-run to simulate the underlying manager calls without touching the system: the safe way to watch what mpm would do before trusting it.

Operations¶

Operation	Supported	Notes
`installed`	✅
`outdated`	✅
`orphans`	✅
`search`	✅
`install`	✅	A package already installed as a dependency is marked explicit by `mpm`.
`upgrade`	✅
`upgrade_all`	✅
`remove`	✅
`sync`	✅
`cleanup`	✅	The `--orphans` flag runs the system-wide orphan sweep.
`doctor`	✅

Configuration¶

Ignore pkg on the mpm CLI by passing the --no-pkg option.
Ignore it for every run in your configuration:
```
[mpm]
pkg = false
```
Raise the timeout of all pkg calls:
```
[mpm.overrides.pkg]
timeout = 900
```

Run mpm config-template pkg to print all overridable settings for your configuration file:

[mpm.overrides.pkg]
cli_names = [
    "pkg",
]
cli_search_path = []
dry_run = false
ignore_auto_updates = true
plan = false
post_args = []
pre_args = []
pre_cmds = []
requirement = ">=1.11"
stop_on_error = false
unmaintained = false
version_cli_options = [
    "--version",
]
version_regexes = [
    "(?P<version>\\S+)",
]

Recipes¶

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

Snapshot and clone a machine: mpm --pkg dump pkg.toml, then mpm restore pkg.toml on the next one.
Export a compliance SBOM: mpm --pkg sbom (CycloneDX by default, --spdx for SPDX).
Gate CI on health: mpm --pkg doctor relays FreeBSD pkg’s own diagnosis and exits non-zero on trouble.

Privilege escalation¶

System-wide manager: mpm wraps its privileged operations in sudo out of the box. Instead of letting the tool prompt mid-run, mpm primes the credential cache up-front, with a single branded password prompt at most. Turn escalation off for rootless setups with --no-sudo or the per-manager sudo override.

Its privileged operations are cleanup, install, remove, sync, upgrade, upgrade_all.

See privilege escalation for the full policy.

Concurrency¶

mpm never runs pkg at the same time as ports: ports keeps no registry of its own and registers what it builds through pkg, whose advisory lock on that shared install database refuses a second writer. Each mutating operation waits for the previous one, even with a higher --jobs, while managers outside this group keep running in parallel.

Only mutations are held back. The read-only queries (installed, outdated, search) take no backend lock and stay fully concurrent.

Cooldown¶

State of FreeBSD pkg’s release-age gating, from the cooldown support table:

Status: ❌ None

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: Distro binary archives (pkg:deb, pkg:rpm, pkg:alpm, pkg:apk)
Retraction: Index revert: removal is an archive operation and the mirror is rebuilt without the package. Debian, for one, requires filing an RM: bug against ftp.debian.org (developers-reference)
Publish date: ❌ the version string is the distro maintainer’s build, carrying no upstream publication date

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

Reference traces¶

A collection of raw native outputs captured from the manager’s own CLI and recorded in the manager source. If you know FreeBSD pkg well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ pkg query "%n %v %c"
7-zip 21.07_2 Console version of the 7-Zip file archiver
ap24-mod_mpm_itk 2.4.7_2 Run each vhost under a separate uid and gid
apache24 2.4.57 Version 2.4.x of Apache web server
aquantia-atlantic-kmod 0.0.5_1 Aquantia AQtion (Atlantic) Network Driver
arcconf 3.07.23971,1 Adaptec SCSI/SAS RAID administration tool
areca-cli-amd64 1.14.7.150519,1 Command Line Interface for ARC-xxxx RAID
base64 1.5_1 Utility to encode and decode base64 files
bash 5.1.12 GNU Project's Bourne Again SHell
beadm 1.4_1 Solaris-like utility to manage Boot Environments on ZFS

$ pkg upgrade --quiet --dry-run
Updating FreeBSD repository catalogue...
FreeBSD repository is up to date.
All repositories are up to date.
Checking for upgrades (312 candidates): 100%
Processing candidates (312 candidates): 100%
The following 466 package(s) will be affected (of 0 checked):

Installed packages to be REMOVED:
    freenas-files: 13.0_1700495253
    py39-midcli: 20190509171453
    py39-middlewared: 13.0_1700495253

New packages to be INSTALLED:
    abseil: 20230125.3 [FreeBSD]
    argp-standalone: 1.5.0 [FreeBSD]
    brotli: 1.1.0,1 [FreeBSD]

Installed packages to be UPGRADED:
    7-zip: 21.07_2 -> 23.01 [FreeBSD]
    apache24: 2.4.57 -> 2.4.58_1 [FreeBSD]
    apr: 1.7.0.1.6.1_1 -> 1.7.3.1.6.3_1 [FreeBSD]
    aquantia-atlantic-kmod: 0.0.5_1 -> 0.0.5_2 [FreeBSD]
    bash: 5.1.12 -> 5.2.21 [FreeBSD]

$ pkg autoremove --quiet --dry-run
Checking integrity... done (0 conflicting)
Deinstallation has been requested for the following 2 packages:

Installed packages to be REMOVED:
    libiconv: 1.17
    pcre: 8.45_3

Number of packages to be removed: 2

Version check¶

The version is extracted from the output of pkg --version with:

r"(?P<version>\S+)"

Upstream project¶

Metrics	`freebsd/pkg`
Activity
Popularity
Metadata

Changelog¶

8.0.0 (2026-09-20)
- Mark a package already installed as a dependency as explicitly installed when mpm install or mpm restore names it, so mpm cleanup --orphans keeps it.
- Stop running ports concurrently with pkg, which holds the advisory lock on the install database both register into.
- Warn and report no package, instead of crashing, when a JSON listing cannot be parsed.
- Fix every operation on FreeBSD, where pkg rejects the global --quiet it was passed, and repair search, which omitted its subcommand and mis-parsed the results.
7.6.1 (2026-08-11)
- Fix the pkg(8) and ports(7) man-page references rendering as broken markup on the manager’s documentation page.
7.4.0 (2026-07-25)
- Plain cleanup no longer removes orphaned packages: their native sweeps moved behind cleanup --orphans. This also stops emerge’s cleanup from triggering its pre-depclean world upgrade unless --orphans is given.
- Mutating operations now escalate through sudo by default, matching each tool’s canonical invocation (sudo port install, sudo pkg install, sudo snap install): MacPorts installs root-owned under /opt/local, the FreeBSD pkg frontend gains the markers its ports sibling already had, and snapd denies state changes from an unprivileged client. Opt out with --no-sudo or a per-manager sudo = false override. pkg passes IGNORE_OSVERSION as a command-line option now, which survives the sudo environment reset where the environment variable would be stripped.
- installed now lists every package registered in the pkg database instead of only explicitly-requested ones: the %a = 0 automatic-flag filter is dropped, and the query invocation loses the literal quote characters it carried, aligning it with the ports invocation reading the same database.
6.2.0 (2026-03-25)
- Add --quiet option to all pkg invocations to reduce log verbosity.
5.15.0 (2024-02-25)
- Add support for pkg on FreeBSD.