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 installations to 15.1-RELEASE.

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

Operators in either case may also optionally rebuild from source.

Upgrading with Source

The procedure for upgrading via source is described in Updating FreeBSD from Source.

For Git use the releng/15.1 branch where any upcoming Security Advisories or Errata Notices will be applied.

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-upgrade(8) may prompt to rebuild or reinstall all third-party applications due to changes in system libraries. Follow those instructions as needed.

  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 via the pkgbase(7) tech preview 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 `date +%Y%m%d`

    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 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 installtion 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 preceeded with a plus (+) character. Note the location of the bootloader, 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

    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 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 (ada0) 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 8, 2026 by Alexander Ziaee