FreeBSD 15.0 brings significant improvements including quantum-resistant cryptography, OpenZFS 2.4, and the new pkgbase system. If you’re running FreeBSD 14.x, the built-in freebsd-update tool handles the entire major version upgrade with minimal downtime. This guide walks through the complete process, from backup to final verification.
Upgrading FreeBSD 14 to FreeBSD 15 using freebsd-update is the traditional binary upgrade method, well suited for production servers where you want a straightforward path. The process involves fetching upgrade patches, installing the new kernel, rebooting, then upgrading userland and packages. The whole procedure takes roughly 30 to 60 minutes depending on your internet speed and disk I/O.
Last verified: March 2026 | Tested upgrade from FreeBSD 14.4-RELEASE to 15.0-RELEASE-p4
What’s New in FreeBSD 15
FreeBSD 15.0 is a major release with several notable changes. Here are the highlights worth knowing before you upgrade:
- pkgbase: The base system can now be managed as packages, though this guide uses the traditional
freebsd-updatemethod. - OpenSSL 3.5 with quantum-resistant cryptography support (ML-KEM and ML-DSA algorithms).
- OpenZFS 2.4 with performance improvements and new features.
- OpenSSH 10 with updated defaults. The upgrade process automatically handles config merges like
UseBlacklistbeing renamed toUseBlocklist. - ABI change from
FreeBSD:14:amd64toFreeBSD:15:amd64, which means all installed packages need rebuilding.
For the full list of changes, see the official FreeBSD 15.0 release announcement.
Prerequisites
Before starting the upgrade, confirm the following:
- A running FreeBSD 14.x system (14.1 or later recommended, tested on 14.4-RELEASE).
- Root access or a user with
sudoprivileges. - At least 2 GB of free disk space for the upgrade files.
- Working network connectivity to reach
update2.freebsd.org. - A full backup of your system. This is a major version upgrade and things can go wrong.
If you need a fresh install instead, check out how to install FreeBSD 15 on Proxmox / KVM.
Step 1: Back Up Your System
Never run a major OS upgrade without a backup. If your system uses ZFS (the default since FreeBSD 14), create a recursive snapshot of all pools:
zfs snapshot -r zroot@pre-upgrade-15Verify the snapshot was created:
zfs list -t snapshotIf something goes wrong during the upgrade, you can roll back with zfs rollback -r zroot@pre-upgrade-15.
For UFS systems without ZFS, create a tar backup of critical directories:
tar czf /backup/pre-upgrade-backup.tar.gz /etc /usr/local/etc /var/db/pkg /rootAlso make sure you have console access (IPMI, KVM, or Proxmox VNC) in case SSH breaks during the upgrade.
Step 2: Update Current System
Before jumping to FreeBSD 15, make sure your current FreeBSD 14.x installation is fully patched. This reduces the number of changes the upgrade tool needs to handle and avoids known issues that were already fixed.
Fetch and install any pending security patches:
freebsd-update fetch installThen upgrade all installed packages to their latest versions on the current release:
pkg upgrade -yReboot if any kernel patches were applied:
rebootAfter the reboot, confirm you’re on the latest 14.x patch level:
freebsd-versionYou should see your current FreeBSD 14.x version confirmed:
14.4-RELEASEStep 3: Fetch the Upgrade
Now start the actual upgrade. The freebsd-update tool will download all patches needed to move from 14.x to 15.0. Use PAGER=cat to prevent the tool from opening a pager for every file diff, which makes the process much smoother over SSH.
PAGER=cat freebsd-update -r 15.0-RELEASE upgradeThe tool starts by fetching metadata and inspecting your system:
Fetching metadata signature for 14.4-RELEASE from update2.freebsd.org... done.
Inspecting system... done.
The following components of FreeBSD seem to be installed:
kernel/generic kernel/generic-dbg world/base world/base-dbg world/lib32 world/lib32-dbg
Does this look reasonable (y/n)? yAnswer y to confirm the detected components. The tool then downloads all required patches and files. This is the longest part of the process, typically taking 20 to 30 minutes:
Fetching 7885 patches
Fetching 6618 files
Attempting to automatically merge changes in files... done.During the merge phase, freebsd-update shows any configuration file changes it needs to apply. One common merge you’ll see is the OpenSSH config update:
--- current version
+++ new version
-UseBlacklist yes
+UseBlocklist yes
Does this look reasonable (y/n)? yReview the proposed changes and answer y if they look correct. When the fetch completes, you’ll see the final instruction:
To install the downloaded upgrades, run 'freebsd-update [options] install'.Step 4: Install Kernel and Reboot
The upgrade is applied in stages. The first install run applies only kernel updates. This keeps the process safe because you get a chance to verify the new kernel boots correctly before touching userland.
freebsd-update installThe output confirms the kernel was installed and tells you to reboot:
Installing updates...
Kernel updates have been installed. Please reboot and run
'freebsd-update [options] install' again to finish installing updates.Reboot the system to load the new FreeBSD 15 kernel:
rebootAfter the system comes back up, verify that you’re running the FreeBSD 15 kernel:
uname -rThe kernel version should now show FreeBSD 15:
15.0-RELEASE-p4At this point, the kernel is on FreeBSD 15 but the userland is still on 14.x. You can confirm this split state by checking freebsd-version:
freebsd-versionThis still reports the old version because userland hasn’t been upgraded yet:
14.4-RELEASEThat’s expected. The next step fixes it.
Step 5: Install Userland
With the new kernel running, it’s safe to upgrade the rest of the system. Run freebsd-update install again to apply userland updates:
freebsd-update installThis stage updates all base system binaries, libraries, and configuration files. It also restarts services that need it:
Restarting sshd after upgrade...
Completing this upgrade requires removing old shared object files.
Please upgrade or rebuild all installed 3rd party software and then run
'freebsd-update [options] install' again.Note that sshd gets restarted automatically. If you’re connected over SSH, your session should survive this, but have console access ready just in case. Don’t run the final freebsd-update install yet because you need to upgrade packages first.
Step 6: Upgrade Packages
The ABI (Application Binary Interface) changed from FreeBSD:14:amd64 to FreeBSD:15:amd64, which means every installed package needs to be rebuilt against the new system libraries. The pkg tool handles this automatically.
Run the package upgrade:
pkg upgrade -yThe first thing you’ll notice is that pkg itself gets reinstalled for the new ABI:
pkg-2.5.1 [FreeBSD-ports] (ABI changed: 'FreeBSD:14:amd64' -> 'FreeBSD:15:amd64')After pkg reinstalls itself, it downloads and installs new versions of all your packages compiled for FreeBSD 15. This can take a while depending on how many packages you have installed. For a general overview of FreeBSD package management, see this FreeBSD and OpenBSD package and service management guide.
Step 7: Final Cleanup
With all packages rebuilt for FreeBSD 15, run freebsd-update install one last time to remove old shared libraries that are no longer needed:
freebsd-update installThe cleanup completes quickly:
Installing updates... done.Now verify the upgrade was successful. Check the full kernel version string:
uname -aYou should see FreeBSD 15.0 across the board:
FreeBSD freebsd 15.0-RELEASE-p4 FreeBSD 15.0-RELEASE-p4 GENERIC amd64Confirm the userland version now matches:
freebsd-versionBoth kernel and userland should report the same version:
15.0-RELEASE-p4Check the package manager version to confirm it’s running the FreeBSD 15 build:
pkg -vThe version should reflect the updated package:
2.5.1Your FreeBSD system is now fully upgraded to 15.0.
Troubleshooting
Here are common issues you might run into during the upgrade and how to fix them.
Not enough disk space
The upgrade downloads thousands of patches and files. If you see errors about insufficient space, freebsd-update stores its working files in /var/db/freebsd-update. Make sure you have at least 2 GB free on the root partition. Clean up old upgrade files if needed:
rm -rf /var/db/freebsd-update/*Then retry the upgrade from the fetch step.
Merge conflicts
If freebsd-update cannot automatically merge a configuration file, it opens the diff in your pager and asks you to resolve it manually. Using PAGER=cat as shown earlier prevents this from blocking the process. If you do hit a conflict, compare your custom changes against the new defaults and keep your modifications where they still apply.
TTY required errors
Running freebsd-update in a non-interactive shell (cron, scripts) can fail with TTY-related errors. Always run the upgrade interactively. If you must automate it, use env PAGER=cat and pipe yes to handle the prompts, but review the output carefully afterward.
Packages fail to install after ABI change
If pkg upgrade fails because the repository hasn’t been updated for FreeBSD 15 yet, force a repository catalog refresh:
pkg update -fThen retry pkg upgrade -y. In rare cases where packages are badly broken, you may need to reinstall them:
pkg install -f packagenameSystem won’t boot after kernel install
If the new kernel fails to boot, use the FreeBSD boot loader menu to select the previous kernel. At the boot prompt, choose “Escape to loader prompt” and type:
unload
set currdev=zfs:zroot/ROOT/default:
load /boot/kernel.old/kernel
bootThis boots the old kernel so you can investigate. If you took a ZFS snapshot before the upgrade, you can roll back entirely with zfs rollback -r zroot@pre-upgrade-15.
Conclusion
Upgrading from FreeBSD 14.x to 15.0 using freebsd-update is a well-tested, reliable process that FreeBSD has refined over many releases. The key is following the three-stage install sequence: kernel first, reboot, userland second, packages third, then final cleanup. Always take a ZFS snapshot before starting so you have an easy rollback path if anything goes wrong.
