FreeBSD 15.1-RELEASE Upgrading Instructions

Abstract

This note details the procedure for upgrading existing installations to FreeBSD 15.1-RELEASE.

Introduction

This document explains the procedure for upgrading existing 14.4-RELEASE or 15.0-RELEASE installations to 15.1-RELEASE. Systems running older releases must be upgraded incrementally to one of these releases before performing this upgrade.

Before upgrading the operating system, back up all filesystems, read the late-breaking errata for known issues and workarounds, and the release note for major changes and incompatibilities.

The procedure for binary upgrades depends on the method used to manage the operating system. To determine this, run the following command:

pkg which /usr/bin/uname

If /usr/bin/uname was not installed by a package is shown, see Upgrading with Distribution Sets below.

If a package name is shown, such as FreeBSD-runtime-15.0, see Upgrading with Base System Packages below.

If upgrading via source, see FreeBSD Handbook chapter on Updating FreeBSD from Source.

Upgrading with Distribution Sets

Systems deployed via distribution sets are upgraded via freebsd-update(8). Systems running 14.4-RELEASE or 15.0-RELEASE can be upgraded as follows:

  1. Apply all Pending Patches:

    Always fetch and apply all pending patches to the current system before upgrading:

    freebsd-update fetch
freebsd-update install

  2. Upgrade the Kernel

    Fetch and install the new kernel:

    freebsd-update upgrade -r 15.1-RELEASE
freebsd-update install

    During this process freebsd-update(8) may ask for help in merging configuration files.

  3. Reboot into the new Kernel

    Reboot into the new kernel before installing the new userland:

    shutdown -r +10min "Rebooting for a kernel upgrade"

  4. Upgrade the Userland

    After rebooting, run freebsd-update(8) again to install the new userland components:

    freebsd-update install

    freebsd-update(8) may prompt to rebuild or reinstall all third-party software due to changes in system libraries. Follow those instructions as needed.

    Tip

    If upgrading from 14.4-RELEASE and reinstalling all third-party software is not possible, install the misc/compat14x package.

  5. Remove Old Files

    Run freebsd-update(8) again to remove stale base system files:

    freebsd-update install

  6. Upgrade the Boot Loader

    To determine which boot loader to update on your system, run the following command:

    sysctl machdep.bootmethod

    Continue to Upgrading the UEFI Boot Loader or Upgrading the BIOS Boot Loader below.

Upgrading with Base System Packages

Systems deployed with a packaged base system are upgraded via pkg(8). Systems running 14.4-RELEASE or 15.0-RELEASE can be upgraded as follows:

  1. Snapshot the Current Installation

    Take a recursive snapshot of the functioning system named with the current date:

    bectl create -r pre-15.1

    The boot loader offers a menu to boot from this if the upgrade needs to be rolled back.

  2. Upgrade the Package Manager

    pkg upgrade -yr FreeBSD-ports pkg

  3. Upgrade the Base System

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

    After the upgrade, review any messages printed by pkg(8). Some packages may require additional configuration steps such as running service <name> setup. Follow those instructions as needed.

  4. Upgrade Third‑party Kernel Modules

    Third party kernel modules must also be upgraded with the base system:

    pkg upgrade -r FreeBSD-ports-kmods

    If the installation is not using these, pkg(8) will reply accordingly.

  5. Check for Failed Configuration Updates

    If pkg(8) is unable to merge configuration file updates, it will install the new configuration as a .pkgnew file. Check for them with the following command:

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

    If they exist, compare them with the deployed version (e.g., diff /etc/rc.conf /etc/rc.conf.pkgnew) and merge any necessary changes.

  6. Upgrade the Boot Loader:

    To determine which boot loader to update on your system, run the following command:

    sysctl machdep.bootmethod

    Continue to Upgrading the UEFI Boot Loader or Upgrading the BIOS Boot Loader below.

Upgrading the UEFI Boot Loader

  1. Identifying the ESP

    Identify the EFI System Partition (ESP) where the boot loader resides by executing the following command:

    efibootmgr -v

    The output should be similar to the following:

     +Boot0000* FreeBSD HD(1,GPT,f859c46d-19ee-4e40-8975-3ad1ab00ac09,0x800,0x82000)/File(\EFI\freebsd\loader.efi)
                       nda0p1:/EFI/freebsd/loader.efi (null)

    The active boot loader entry is preceded with a plus (+) character. Note the location of the bootloader, in this case EFI/freebsd/loader.efi on nda0p1, though systems vary.

  2. Mounting the ESP

    If the ESP is not already mounted at /boot/efi, mount the partition listed in the efibootmgr output:

    mount_msdosfs /dev/nda0p1 /boot/efi

  3. Install the Boot Loader

    On AMD64 systems, upgrade the boot loader in the configured and default positions by executing the following commands:

    cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi
cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi

    Note that some installations may not have freebsd/loader.efi.

    For AArch64 systems, execute the following commands instead:

    cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi
cp /boot/loader.efi /boot/efi/efi/boot/bootaa64.efi

    Other architectures vary accordingly; consult loader.efi(8) if necessary.

  4. Finish

    Reboot after completing the upgrade to FreeBSD 15.1-RELEASE:

    shutdown -r +10min "Rebooting for a system upgrade"

Upgrading the BIOS Boot Loader

For systems that boot via BIOS or UEFI CSM and use the GPT partition scheme, bootstrap upgrades are optional unless a ZFS root pool is upgraded (which is discouraged). Upgrades are only possible if the freebsd-boot partition is at least 180K; 512K is now standard.

  1. Identify the freebsd-boot Partition

    Identify the freebsd-boot device name and partition index by executing the following command:

    gpart show

    The output should be similar to the following:

     =>       34  246162605  ada0  GPT  (224G)
          34       1024     1  freebsd-boot  (512K)

    Note the name (ada) and index (1) of the freebsd-boot partition.

  2. Upgrade the Boot Loader

    When using ZFS on BIOS, upgrade the bootcode by running the following command:

    gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0

    Where 1 is the index of the freebsd-boot partition.

    If booting from a storage array, repeat this step for all disks in the pool.

    When using UFS on BIOS, execute the following command instead:

    gpart bootcode -b /boot/pmbr -p /boot/gptboot -i 1 ada0

  3. Finish

    Reboot after completing the upgrade to FreeBSD 15.1-RELEASE:

    shutdown -r now

Last modified on: June 16, 2026 by Vladlen Popolitov