Synopsis #
FreeBSD uses separate operations for security and errata updates to the base system, upgrades between releases, and updates to third-party packages. FreeBSD 15 also offers pkgbase, so the base-system maintenance command depends on how that system was installed.
Before making a change, identify the installed release and the intended outcome:
$ freebsd-version -kru
The three values report the running kernel, installed kernel, and installed userland. A mismatch can be expected between installing a kernel update and rebooting.
Confirm that the installed release still receives fixes on the supported FreeBSD releases page .
Choose the operation #
| Intended result | Distribution-set base system | Packages installed with pkg |
|---|---|---|
| Apply security and errata fixes within the current release | freebsd-update fetch followed by freebsd-update install | pkg update followed by pkg upgrade |
| Move to another FreeBSD release | Follow the release-upgrade procedure for freebsd-update | Upgrade packages after the base system at the point specified by the official procedure |
| Maintain a pkgbase installation | Use the configured pkgbase repositories and pkg workflow | Use pkg |
Do not mix the distribution-set and pkgbase procedures for the base system. The installation method is part of the system’s maintenance model.
Update a distribution-set base system #
Run the fetch and install phases as root:
# freebsd-update fetch
# freebsd-update install
Read the output before proceeding. If a kernel update was installed, reboot before relying on the new kernel:
# shutdown -r now
After the reboot, confirm the versions again:
$ freebsd-version -kru
freebsd-update rollback can roll back the most recent installed update, but it is not a substitute for a tested backup and may itself require a reboot.
The binary updater maintains the GENERIC kernel. A host with a custom kernel needs an explicit source, rebuild, installation, and fallback plan after relevant updates. See Choose a custom kernel, module, or loader setting before making that maintenance exception permanent.
Update third-party packages #
Refreshing repository metadata and upgrading installed packages are separate from updating the base system:
# pkg update
# pkg upgrade
Review the proposed removals, replacements, and repository changes before confirming. Services that load updated libraries generally need to be restarted.
Upgrade to another release #
A release upgrade changes more than patch-level updates. Back up the system, verify free space, read the target release notes and errata, and use the exact sequence in the official procedure. The sequence contains multiple install and reboot phases; omitting one can leave the running kernel and userland out of sync.
For a distribution-set installation, begin with the FreeBSD Handbook upgrade procedure . For pkgbase, use the pkgbase documentation that matches the installed release and repository configuration.
An upgrade to 15.1-RELEASE can begin directly from 14.4-RELEASE or 15.0-RELEASE. An older installation must first be upgraded incrementally to one of those releases. Follow the 15.1-RELEASE upgrading instructions rather than inferring a sequence from version numbers.
The 15.1 upgrade checklist
turns those release instructions into a preparation, execution, and verification path. If a saved freebsd-update transaction stops between phases, use the interrupted-update recovery guide
instead of deleting its state or starting a different target upgrade.