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 installed kernel, running kernel, and installed userland, in that order. The first two can differ after a kernel update until rebooting. The userland patch suffix need not match the kernel’s suffix when a fix affects only one component.
Confirm that the installed release still receives fixes on the supported FreeBSD releases page .
Choose the operation #
Distribution sets, such as base.txz and kernel.txz, install the base operating system from archives. Third-party packages add applications managed by pkg. Pkgbase installs the base system as packages too, so its update procedure differs from a distribution-set installation.
| 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 #
On a pkgbase host, an unqualified pkg upgrade can also update base packages when their repository is enabled. Select a repository explicitly when the maintenance window covers only one part of the system.
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. For repository or architecture errors, use Resolve a package repository or ABI mismatch .
Update a pkgbase system within its release #
To try pkgbase on a traditional installation, follow the test conversion guide . The commands below maintain a system that already uses it.
Confirm the installation method and effective repositories first:
$ pkg which /usr/bin/uname
$ pkg repositories
A result naming FreeBSD-runtime identifies a packaged base. Confirm that its base repository points to the installed release, rather than changing the release URL during a patch update. The official repository is normally named FreeBSD-base; substitute its actual name on a customized installation.
Refresh and preview that repository alone:
# pkg update -r FreeBSD-base
# pkg upgrade -n -r FreeBSD-base
After reviewing the transaction and preserving the recovery point, apply it:
# pkg upgrade -r FreeBSD-base
Review package messages and any configuration files requiring a merge. Reboot when the kernel or other base components require it, then repeat freebsd-version -kru and check essential services. Do not run freebsd-update install as an additional pkgbase maintenance step.
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.