13.1 Updating FreeBSD with freebsd-update

Warning

freebsd-update supports RELEASE, ALPHA, BETA, and RC versions on amd64 and arm64 (aarch64) architectures. CURRENT, STABLE, and PRERELEASE branches do not provide binary updates; using freebsd-update on these branches will result in an error and exit. These branches must be updated through source code compilation or PkgBase.

freebsd-update is the base system update tool for FreeBSD, supporting the download, verification, and installation of binary updates from the official FreeBSD update servers. It can also be used for upgrades and rollbacks across RELEASE versions.

Note

Only ALPHA, BETA, RC, and RELEASE versions on amd64 and arm64 (aarch64) architectures provide update sources. CURRENT, STABLE, and PRERELEASE do not have binary updates. For information on architecture support levels, see: FreeBSD Project. Supported Platforms[EB/OL]. [2026-03-26]. https://www.freebsd.org/platforms.

Note

For ZFS-related upgrades, see the ZFS chapter.

History

FreeBSD provides the utility freebsd-update for installing system updates, including upgrades to new major versions. freebsd-update was first included in the base system with FreeBSD 6.2-RELEASE for security updates and errata patches; the upgrade command was introduced in FreeBSD 6.3-RELEASE, and by 7.0-RELEASE it officially became the supported upgrade pathway.

References

• FreeBSD Project. FreeBSD 6.2-RELEASE Release Notes[EB/OL]. [2026-04-16]. https://www.freebsd.org/releases/6.2R/relnotes.html. Release notes, "The freebsd-update(8) utility is now included in the FreeBSD base system."
• FreeBSD Project. FreeBSD 7.0-RELEASE Announcement[EB/OL]. [2026-03-25]. https://www.freebsd.org/releases/7.0R/announce/. Official announcement confirming freebsd-update as the supported binary update tool for version upgrades, security fixes, and errata patches.
• FreeBSD Project. freebsd-update -- fetch, install, and rollback FreeBSD updates[EB/OL]. [2026-04-17]. https://man.freebsd.org/cgi/man.cgi?query=freebsd-update&sektion=8. FreeBSD system update tool manual page.

Replacing the Default Text Editor with a Simpler One

Bash, Zsh, or sh

# export EDITOR=/usr/bin/ee  # Switch the default editor from vi to ee
# export VISUAL=/usr/bin/ee  # Switch the visual editor from vi to ee

csh / tcsh

# setenv EDITOR /usr/bin/ee  # Switch the default editor from vi to ee
# setenv VISUAL /usr/bin/ee  # Switch the visual editor from vi to ee

Check and Verify

• View the current terminal default text editor:

# echo $EDITOR
/usr/bin/ee

• View the current terminal visual text editor:

# echo $VISUAL
/usr/bin/ee

Routine Patch/Security Updates (X.Y-RELEASE → X.Y-RELEASE-pN)

Warning

Whether performing a major version update, point release update, or routine update, this procedure should be executed first. It cannot be skipped, otherwise missing dependencies or an unbootable system may result.

FreeBSD Version Check

# freebsd-version -kru
14.3-RELEASE
14.3-RELEASE
14.3-RELEASE

Performing the Update

• Fetch updates

# freebsd-update fetch

When information similar to the following appears:

usr/include/c++/v1/tr1/vector usr/include/c++/v1/tr1/version usr/include/c++/v1/tr1/wchar.h usr/include/c++/v1/tr1/wctype.h usr/include/c++/v1/unwind-arm.h
usr/include/c++/v1/unwind-itanium.h usr/include/c++/v1/unwind.h
usr/include/crypto/cryptodev.h usr/include/crypto/cbcmac.h usr/include/crypto/deflate.h usr/include/crypto/gfmult.h usr/include/crypto/gmac.h
usr/include/crypto/rijndael.h usr/include/crypto/rmd160.h usr/include/crypto/xform.h
usr/lib/clang/19.1.7/include
: q # Enter q and press Enter to exit

The above paths are example output only; actual path names and quantities may differ slightly on your system. Please refer to the actual output.

This lists the files that have changed; after confirming, enter the letter q (quit) and press Enter.

Then install the updates:

# freebsd-update install

For automated periodic update checks, use freebsd-update cron instead, which introduces a random delay of 1 to 3600 seconds before executing fetch.

Verifying the Updated FreeBSD Version

• View the FreeBSD version after updating:

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE
14.3-RELEASE-p6

Note

Sometimes patches do not affect the kernel, so the kernel version will not change and cannot be reflected by uname -r, but the userland version will change. Therefore, two version numbers may be displayed; the higher one should be taken as the current version.

Reboot the system:

# reboot

Check the FreeBSD version:

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE-p5
14.3-RELEASE-p6

Major Version Upgrades (X.Z-RELEASE-pN → A.0-RELEASE)

Note

The slow download speed of freebsd-update is not due to its update servers being located overseas (the same issue exists when using overseas servers). It may be related to its design; freebsd-update is a pure Shell script consisting of thousands of lines of code. This is a long-standing issue.

freebsd-update upgrade may require up to 500 MB of space in its working directory (default /var/db/freebsd-update/), depending on the installed base system components. If the upgrade is interrupted, use the -F flag to force fetch to continue processing the unfinished upgrade.

Example: Upgrading from FreeBSD 14.3-RELEASE to 15.0-RELEASE

Check Version

# freebsd-version -kru
14.3-RELEASE-p5
14.3-RELEASE-p5
14.3-RELEASE-p6

Warning

Since changes between major versions may affect the freebsd-update tool itself, it is essential to:

First update to the latest patch version of the current version (e.g., X.Y-RELEASE-pN), then update to the latest point release (e.g., X.Z-RELEASE).

Next, update to the latest point release and the latest patch version on that point release (e.g., X.Z-RELEASE-pN).

Finally: Complete the major version upgrade (X.Z-RELEASE-pN → A.0-RELEASE).

See: libsys.so.7 not found when upgrading userland with legacy freebsd-update[EB/OL]. [2026-03-26]. https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=289769.

Update to 15.0-RELEASE

Upgrade the system to FreeBSD 15.0-RELEASE:

# freebsd-update upgrade -r 15.0-RELEASE

……When information similar to the following appears, follow the instructions below……

src component not installed, skipped
Looking up update.FreeBSD.org mirrors... 3 mirrors found.
Fetching metadata signature for 14.3-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata patches.. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.

The following components of FreeBSD seem to be installed:
kernel/generic kernel/generic-dbg world/base world/lib32

The following components of FreeBSD do not seem to be installed:
world/base-dbg world/lib32-dbg

Does this look reasonable (y/n)? y # Enter y and press Enter to confirm the base component installation status

Fetching metadata signature for 15.0-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system...

…………This is checking the system; from the above Enter to here, you need to wait about 10 minutes…………

Fetching metadata signature for 15.0-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.
Fetching files from 14.3-RELEASE for merging... done.
Preparing to download files... done.

…………This is preparing the files to download; you need to wait about 15 minutes…………

Fetching 6735 patches.....10....20....30....40....50....60....70....80....90.

………………Below you need to wait about 30 minutes. Note that for cross-major version updates, sometimes you need to wait 5 hours or more; this is normal.…………

....100....110....120....130....140....150....160....170....180....190....200

…………Omitted in the middle…………

20....6630....6640....6650....6660....6670....6680....6690....6700....6710....6720....6730.. done.
Applying patches...

………………Applying patches; you need to wait about 5 minutes…………

Applying patches... done.
Fetching 880 files... ....10....20....30....4

………………Omitting part of the progress bar…………

0....880 done.
Attempting to automatically merge changes in files... done.

The following file could not be merged automatically: /etc/pkg/FreeBSD.conf
Press Enter to edit this file in /usr/bin/ee and resolve the conflicts
manually...

……This prompts you to press Enter to edit files that could not be automatically merged and require manual resolution……

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/login.conf:
--- current version
+++ new version

……The changed files are listed here; some output is omitted……

 #site:\
-#      :ignoretime:\
 #      :passwordtime@:\
 #      :refreshtime@:\
 #      :refreshperiod@:\
 #      :sessionlimit@:\
 #      :autodelete@:\
Does this look reasonable (y/n)? # Enter y and press Enter to confirm system file changes

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/pkg/FreeBSD.conf:
--- current version
+++ new version

……The changed files are listed here; some output is omitted……

Does this look reasonable (y/n)?  # Enter y and press Enter to confirm system file changes

The following changes, which occurred between FreeBSD 14.3-RELEASE and
FreeBSD 15.0-RELEASE have been merged into /etc/ssh/sshd_config:
--- current version
+++ new version

……The changed files are listed here; some output is omitted……

 # override default of no subsystems
Does this look reasonable (y/n)? # Enter y and press Enter to confirm system file changes

The following files are affected by updates. No changes have
been downloaded, however, because the files have been modified
locally:
/etc/ssl/cert.pem
(END) # The above are the changed files; after confirming, enter q and press Enter to exit

# The above paths are example output only; actual path names and quantities may differ slightly on your system.

The following files will be removed as part of updating to
15.0-RELEASE-p0:
/.cshrc
/.profile
/boot/kernel/callout_test.ko
/boot/kernel/geom_bde.ko
/boot/kernel/geom_vinum.ko

…………Omitted in the middle; these are the files to be removed…………

/usr/share/examples/sound/sndstat_nv.c
: # Enter q to confirm changes until no new content appears

…………Omitted in the middle…………

The following files will be added as part of updating to
15.0-RELEASE-p0:
/boot/firmware/iwm3160fw
/boot/firmware/iwm3168fw
/boot/firmware/iwm7260f

…………Omitted in the middle; these are the newly added files…………

/boot/kernel/nvmf_tcp.ko
/boot/kernel/nvmf_transport.ko
/boot/kernel/nvmft.ko
/boot/kernel/p9fs.ko
: # Enter q to confirm changes until no new content appears

The following files will be updated as part of updating to
15.0-RELEASE-p0:
/COPYRIGHT
/bin/[
/bin/cat

…………Omitted in the middle; these are the updated files…………

/bin/kenv
/bin/kill
/bin/link
/bin/ln
/bin/ls
/bin/mkdir
/bin/mv
/bin/nproc
To install the downloaded upgrades, run 'freebsd-update [options] install'.

Run freebsd-update install to install the updates:

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates...
Kernel updates have been installed.  Please reboot and run
'freebsd-update [options] install' again to finish installing updates.

Kernel updates have been installed:

# freebsd-version -kru
15.0-RELEASE
14.3-RELEASE-p5
14.3-RELEASE-p6

As can be seen, the currently installed kernel version and patch level is 15.0-RELEASE. However, the userland and the currently running system are still 14.3-RELEASE, so a reboot is required as instructed by freebsd-update:

# reboot

Run freebsd-update install to install the userland updates:

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates...
Restarting sshd after upgrade
Performing sanity check on sshd configuration.
Stopping sshd.
Waiting for PIDS: 906.
Performing sanity check on sshd configuration.
Starting sshd.

Completing this upgrade requires removing old shared object files.
Please rebuild all installed 3rd party software (e.g., programs
installed from the ports tree) and then run
'freebsd-update [options] install' again to finish installing updates.

Reinstall pkg itself to update the ABI to 15.0-RELEASE:

# pkg bootstrap -fy
Bootstrapping pkg from pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64/quarterly, please wait...
Verifying signature with trusted certificate pkg.freebsd.org.2013102301... done
Installing pkg-2.4.2...
package pkg is already installed, forced install
Extracting pkg-2.4.2: 100%

Update the ABI of third-party programs to 15.0-RELEASE:

# pkg upgrade
Updating nju repository catalogue...
Fetching meta.conf:   0%
Fetching data.pkg: 100%    7 MiB   7.6MB/s    00:01
Processing entries: 100%
nju repository update completed. 35765 packages processed.
All repositories are up to date.
Updating database digests format: 100%
Checking for upgrades (215 candidates): 100%
Processing candidates (215 candidates): 100%
The following 223 package(s) will be affected (of 0 checked):

New packages to be INSTALLED:
	ceres-solver: 2.2.0_10

…………Omitted in the middle…………

The process will require 45 MiB more space.
687 MiB to be downloaded.

Proceed with this action? [y/N]:  # Enter y and press Enter to continue

…………Omitted in the middle…………

Proceed with this action? [y/N]:  # Enter y and press Enter to continue; this may appear multiple times

The update of third-party programs is now complete.

Run freebsd-update again to complete the update process.

# freebsd-update install
src component not installed, skipped
Creating snapshot of existing boot environment... done.
Installing updates... done.

Verify the operating system version:

# freebsd-version -kru
15.0-RELEASE
15.0-RELEASE
15.0-RELEASE

System update complete.

Troubleshooting and Outstanding Issues

Rolling Back Updates

Roll back the most recent system update:

# freebsd-update rollback

pkg Cannot Find .so Files

Run the following command in the terminal to force-initialize the pkg package manager:

# pkg bootstrap -f

FreeBSD Upgrade Error Resulting in Missing ntpd User

Run the following commands in the terminal:

# pw groupadd ntpd -g 123  # Create the ntpd user group with GID 123
# pw useradd ntpd -u 123 -g ntpd -h - -d /var/db/ntp -s /usr/sbin/nologin -c "NTP Daemon"  # Create the ntpd user with UID 123, home directory /var/db/ntp, login disabled, for NTP daemon only

Exercises

1. Read the source code of the freebsd-update script, rewrite it using a high-level programming language, and verify whether it can significantly improve update speed.
2. Create a freebsd-update mirror site.
3. The binary patch model of freebsd-update relies on precise tracking of base system component versions, while third-party software updates are managed by pkg. Analyze the advantages of this "base system and Ports separation" update strategy in ensuring ABI (Application Binary Interface) compatibility, and its limitations on rolling update requirements.