FreeBSD pkg

ID

pkg

Home page

https://github.com/freebsd/pkg

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

Every call

pkg --quiet <command>

Issues and PRs

📦 manager: pkg-based

Source

meta_package_manager/managers/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.

Note

outdated parses pkg upgrade --dry-run rather than pkg version, because only the dry-run names the target version each package would move to.

Caution

sync forces IGNORE_OSVERSION=yes: a package built for a newer FreeBSD than the running kernel would otherwise trigger an interactive confirmation that hangs the subprocess. It is passed as a -o command-line option rather than an environment variable, which sudo’s environment reset would strip from the escalated call. Support for that setting is also why the version floor is 1.11.

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 --dry-run

mpm --pkg outdated

Search for a package

pkg search --raw --raw-format json-compact --search name nginx

mpm --pkg search <pkg>

Install a package

sudo pkg install --yes dmg2img

mpm install pkg:pkg/dmg2img

Upgrade one package

sudo pkg upgrade --yes dmg2img

mpm --pkg upgrade dmg2img

Upgrade everything

sudo pkg upgrade --yes

mpm --pkg upgrade --all

Remove a package

sudo pkg delete --yes dmg2img

mpm remove pkg:pkg/dmg2img

List orphaned dependencies

pkg autoremove --dry-run

mpm --pkg orphans

Clear caches

sudo pkg clean --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

✓

upgrade

✓

upgrade_all

✓

remove

✓

sync

✓

cleanup

✓

--orphans runs the system-wide orphan sweep

doctor

✓

Selecting and configuring pkg

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

[mpm]
pkg = false

The arguments and environment variables listed in the box atop this page are forced on every pkg 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.pkg]
timeout = 900

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

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.

See privilege escalation for the full policy.

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); --allow-unsupported-managers opts back in.

Version probe

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

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

Reference traces

Raw native outputs captured in the manager source: the reference mpm’s parsers were written against. 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 --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 version --like "<"
Updating FreeBSD repository catalogue...
FreeBSD repository is up to date.
All repositories are up to date.
7-zip-21.07_2                      <
apache24-2.4.57                    <
apr-1.7.0.1.6.1_1                  <
aquantia-atlantic-kmod-0.0.5_1     <
bash-5.1.12                        <

$ pkg --quiet autoremove --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

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 --pkg installed --output json, or csv, toml, yaml), each package carrying a purl and a version comparable across managers.

Changelog

  • 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.