Upgrade 14.4 or 15.0 to FreeBSD 15.1

Synopsis #

FreeBSD 15.1-RELEASE supports a direct binary upgrade from 14.4-RELEASE or 15.0-RELEASE when the host uses distribution sets. The official pkgbase procedure covers a 15.0-RELEASE pkgbase host. It does not document a pkgbase upgrade directly from 14.4, so this guide does not infer one.

The procedure includes a reboot between kernel and userland installation, a later cleanup phase, third-party package work, and a boot-loader decision. Reserve console access and enough time to complete every phase.

Establish the maintenance method #

Record the installed versions and determine whether /usr/bin/uname belongs to pkgbase:

$ freebsd-version -kru
$ pkg which /usr/bin/uname

Use the distribution-set path when pkg reports that /usr/bin/uname was not found in the package database. Use the pkgbase path only when it reports a base package such as FreeBSD-runtime-15.0. A source-built system needs the source-upgrade procedure and is outside this checklist.

Do not start when the release reported by freebsd-version is older than 14.4 or 15.0. Follow an incremental, supported path first.

Prepare the maintenance window #

Read the 15.1 release notes and 15.1 errata .
Verify a restorable backup outside the host.
Confirm remote-console or physical-console access.
Record gpart show, zpool status, df -h, pkg -vv, and the enabled repositories.
Save locally maintained configuration, especially /etc, /usr/local/etc, loader configuration, firewall rules, and custom kernels.
Disable any scheduled freebsd-update job for the upgrade window.

For a ZFS-root system, create a boot environment before changing the base system:

# bectl create -r pre-15.1
$ bectl list

A boot environment is a fast route back to the earlier root filesystem, not a replacement for a backup. The boot-environment recovery guide explains its limits.

Upgrade a distribution-set host #

First bring the source release to its current patch level:

# freebsd-update fetch
# freebsd-update install

Reboot first if that update installed a kernel whose version differs from the running kernel. Then fetch the 15.1 upgrade and install its kernel phase:

# freebsd-update upgrade -r 15.1-RELEASE
# freebsd-update install
# shutdown -r now

After the host boots the new kernel, install the new userland:

$ freebsd-version -kru
# freebsd-update install

Follow any prompt to rebuild or reinstall third-party software. An upgrade from FreeBSD 14 changes the major ABI. The official procedure notes misc/compat14x as a temporary compatibility option when immediate reinstallation is impossible, but compatibility libraries should not replace the planned package rebuild.

For the 14.4-to-15.1 major-version transition, replace installed packages with packages built for the new ABI at the requested package phase:

# pkg-static upgrade -f

For the 15.0-to-15.1 minor-version transition, refresh and review the ordinary package transaction instead:

# pkg update
# pkg upgrade

Run the cleanup phase after the package step requested by freebsd-update:

# freebsd-update install

If an invocation was interrupted, do not delete /var/db/freebsd-update. Continue with the interrupted-update recovery procedure .

Upgrade a 15.0 pkgbase host #

The pkgbase command-line overrides below are specific to the official 15.1 upgrading instructions. They should not become permanent global pkg settings.

Bring the 15.0 base repository current, then upgrade the base packages for 15.1:

# pkg upgrade -r FreeBSD-base
# pkg -oABI=FreeBSD:15:$(uname -p) -oOSVERSION=1501000 upgrade -r FreeBSD-base

Upgrade packaged third-party kernel modules when that repository is configured:

# pkg upgrade -r FreeBSD-ports-kmods

Review failed configuration merges before rebooting:

# find /etc /usr/local/etc -name '*.pkgnew' -ls

Compare each result with the deployed file and merge required local settings deliberately.

Update the boot loader for the actual layout #

On amd64, identify the boot method:

$ sysctl machdep.bootmethod

AArch64 uses UEFI. UEFI, BIOS with ZFS, BIOS with UFS, mirrored pools, and nonstandard EFI System Partition paths require different targets. Follow the boot-loader section of the official 15.1 upgrading instructions using the device names and partition indexes recorded from this host. Do not paste example device names such as ada0 or nda0p1 without verifying them.

Verify the result #

After the final reboot, confirm the running and installed versions, pool health, package database, and services:

$ freebsd-version -kru
# pkg check -d -a
# service service-name status

On a ZFS host, also confirm pool health:

$ zpool status

Replace service-name with each important service. A host upgraded from FreeBSD 14 also needs third-party packages built for the FreeBSD 15 ABI. The package repository and ABI troubleshooting guide provides an evidence-first check when this fails.

Keep the pre-upgrade boot environment until normal workloads, remote access, scheduled jobs, package updates, and a controlled reboot have been verified.