> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-13-freebsd-system-updates/di-13.1-jie-shi-yong-freebsd-update-geng-xin-freebsd.md). # 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]. . > **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]. . 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]. . 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]. . FreeBSD system update tool manual page. ## Replacing the Default Text Editor with a Simpler One ### Bash, Zsh, or sh ```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 ```sh # 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: ```sh # echo $EDITOR /usr/bin/ee ``` * View the current terminal visual text editor: ```sh # 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 ```sh # freebsd-version -kru 14.3-RELEASE 14.3-RELEASE 14.3-RELEASE ``` ### Performing the Update * Fetch updates ```sh # freebsd-update fetch ``` When information similar to the following appears: ```sh 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: ```sh # 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: ```sh # 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: ```sh # reboot ``` Check the FreeBSD version: ```sh # 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](https://freebsd-questions.freebsd.narkive.com/xjVoetUM/why-is-freebsd-update-so-horrible-slow). > > `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 ```sh # 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]. . ### Update to 15.0-RELEASE Upgrade the system to FreeBSD 15.0-RELEASE: ```sh # 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: ```sh # 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: ```sh # 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`: ```sh # reboot ``` Run `freebsd-update install` to install the userland updates: ```sh # 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: ```sh # 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: ```sh # 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. ```sh # freebsd-update install src component not installed, skipped Creating snapshot of existing boot environment... done. Installing updates... done. ``` Verify the operating system version: ```sh # 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: ```sh # freebsd-update rollback ``` ### pkg Cannot Find `.so` Files Run the following command in the terminal to force-initialize the pkg package manager: ```sh # pkg bootstrap -f ``` ### FreeBSD Upgrade Error Resulting in Missing ntpd User Run the following commands in the terminal: ```sh # 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://book.bsdcn.org/ask/flat/chapter-13-freebsd-system-updates/di-13.1-jie-shi-yong-freebsd-update-geng-xin-freebsd.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.