FreeBSD · Release Upgrade · Branch Strategy

How to Upgrade Any Supported FreeBSD Release and Choose the Right Branch for Production

A good FreeBSD upgrade guide should do two things clearly. First, it should show the command flow for moving from one supported -RELEASE version to another without locking the reader to a single old target such as 13.1. Second, it should explain the branch model well enough that a production or enterprise operator can tell when to stay on a release branch, when to test a stable branch, and when to avoid a development branch entirely.

What this covers

A generic upgrade workflow for supported binary -RELEASE systems, plus a practical explanation of releng, stable, and CURRENT.

Who this is for

Administrators running FreeBSD on servers, long-lived workstations, appliances, or enterprise systems who want a repeatable upgrade path and a clearer release strategy.

Main rule

For most production systems, prefer supported -RELEASE branches. Treat -STABLE as an engineering track and -CURRENT as development.

The practical distinction freebsd-update is for supported binary -RELEASE systems. Tracking -STABLE or -CURRENT is a different operating model that uses source and Git, not the normal release-upgrade workflow.

Branch model

What the FreeBSD version branches actually mean

Many upgrade guides fail because they talk about versions without explaining the branch model behind them. In FreeBSD, branch names tell you what kind of system you are operating and how much change you are choosing to absorb between maintenance windows.

Branch type	What it means	How it is usually managed	When it is preferable
releng/X.Y Example: releng/14.4	The security branch for a specific release. This is the familiar X.Y-RELEASE track, with security and errata updates applied over time.	Normally updated with freebsd-update on binary installations.	Best default for production, enterprise, appliances, and conservative servers.
stable/X Example: stable/14	The development branch from which releases in that major version line are made. It moves more slowly than CURRENT, but it is still a development branch.	Tracked from source with Git and normal source-build procedures.	Useful for advanced operators, internal platform teams, and staging environments that want earlier fixes or want to help validate the next release. Not the default choice for enterprise production.
main / CURRENT	The bleeding edge of FreeBSD development, including work in progress and transitional changes.	Tracked from source with Git, with active attention to mailing lists and /usr/src/UPDATING.	Best for FreeBSD developers, active testers, and labs. Not appropriate for normal production use.
ALPHA, BETA, RC	Pre-release snapshots cut during the release process.	Temporary test installations or upgrade rehearsals.	Useful in validation environments when you want early visibility into an upcoming release. Avoid in production.

Current support planning

Supported FreeBSD branches to plan against

The most important upgrade rule is simple: stay on a supported branch. If a system is on an older unsupported release, the project strongly encourages upgrading to one of the currently supported branches.

Branch	Release name	Expected end of support	Production meaning
stable/15	development line for FreeBSD 15	December 31, 2029	Long support runway, but still a development branch rather than the default enterprise target.
releng/15.0	15.0-RELEASE	September 30, 2026	Current 15.x release line. Good when you want the newest major release and have validated your applications.
stable/14	development line for FreeBSD 14	November 30, 2028	Long-lived major-version line, but still better suited to engineering and staging than general production.
releng/14.4	14.4-RELEASE	December 31, 2026	Very strong production target for conservative operators who want a mature major version with active support.
releng/14.3	14.3-RELEASE	June 30, 2026	Still supported, but close enough to EoL that it is usually a transition stop rather than the branch to settle on.
stable/13 / releng/13.5	13.5-RELEASE	April 30, 2026	Suitable mainly for short transition windows, compatibility holdouts, or upgrade planning. Too near EoL for fresh production commitments.

Enterprise reading of this table If you want the safest default, settle on a supported 14.x-RELEASE branch unless you have a specific reason to standardize on 15.x. If you are still on 13.5, plan your move soon rather than treating it as a long-term resting place.

Preparation

Prepare the system before you touch the target release

A clean upgrade starts before the upgrade command itself. Back up data, configuration, and anything you would not want to recreate by hand. Then verify what you are actually running now.

freebsd-version -kru
uname -r

This gives you a quick view of the installed kernel, userland, and running kernel version before the change. It also helps you confirm later that the new system really booted into the intended release.

If you are using a custom kernel, remember that only the GENERIC kernel can be automatically updated by freebsd-update. Keep a copy of GENERIC available and be prepared to rebuild and reinstall your custom kernel after the upgrade if needed.

Generic workflow

Use this command sequence for any supported -RELEASE upgrade

The release number is the only part that changes. The shape of the workflow stays the same whether you are doing a minor upgrade inside one major line or a major upgrade to the next major line.

1. Bring the current system fully up to date first

freebsd-update fetch
freebsd-update install

Do not start a release upgrade from a neglected system. Patch the current release first so you are upgrading from a clean, supported baseline.

2. Start the release upgrade

freebsd-update -r TARGET-RELEASE upgrade

Replace TARGET-RELEASE with the exact release you intend to land on, such as a newer point release in the same major line or the first release in the next major line.

3. Review prompts and file merges carefully

During the upgrade, FreeBSD may ask you to review configuration-file changes. This is the point where a rushed upgrade often becomes a broken upgrade. Slow down, compare changes, and keep backups of files in /etc if you need a safe fallback.

4. Apply the first installation pass

freebsd-update install

5. Reboot into the upgraded kernel and base state

reboot

6. Complete the remaining installation pass

freebsd-update install

Depending on the upgrade path, more than one install pass may be needed. Read the prompts and keep running the install phase until FreeBSD reports that the staged upgrade work is complete.

Packages after the base upgrade

Refresh the package layer after the release upgrade

Once the base system has moved to the new release, refresh package metadata and upgrade installed packages so userland software is aligned with the new ABI and repository state.

pkg update -f
pkg upgrade

If your package manager is missing or broken, FreeBSD also documents bootstrapping or reinstalling pkg. Most systems, however, will just need a forced metadata refresh and a normal package upgrade.

Package policy for enterprise servers For most production systems, the Quarterly packages branch is the safer default because it favors a more predictable and stable update experience. Use Latest when you intentionally want newer package versions and accept a faster pace of change.

Production guidance

Which branch should you choose in production or enterprise?

Choose -RELEASE for most production systems

This is the best default when uptime, repeatability, security updates, and predictable maintenance windows matter more than seeing new code early. That includes enterprise servers, storage nodes, edge appliances, and small infrastructure teams that want a steady operating model.

Choose -STABLE only if your organization can validate it like a software platform

-STABLE is not the same thing as “stable enough for everyone.” It is the engineering branch from which releases are made. It is appropriate when you have staging, test automation, upgrade rehearsals, and the staff time to track source-level changes. It is not the branch to put on production just because the name sounds reassuring.

Do not choose -CURRENT for normal enterprise production

-CURRENT is for development, active testing, and deep FreeBSD familiarity. It is useful for contributors and advanced labs, not for ordinary line-of-business systems that need predictable behavior.

Use older supported releases only as transition branches

A release that is still supported but close to end-of-life can be useful when you need a conservative stepping stone for compatibility, vendor timing, or migration planning. It is usually not the right long-term landing point for a new production deployment.

Verification

Verify the system after the upgrade

Do not declare success just because the machine rebooted. Confirm the reported version, check critical services, verify package health, and make sure the running kernel matches the intended userland.

freebsd-version -kru
uname -r
pkg check -da

On an enterprise system, this is also where you verify storage pools, jails, network services, monitoring agents, backup agents, and any custom kernel or loader settings that matter to your environment.

Reference

The core release-upgrade flow at a glance

Order	Command	Purpose
1	freebsd-update fetch freebsd-update install	Bring the current supported release up to date before starting the version change.
2	freebsd-update -r TARGET-RELEASE upgrade	Start the upgrade to the target supported release.
3	freebsd-update install	Apply the first staged install pass.
4	reboot	Boot into the upgraded kernel/base state.
5	freebsd-update install	Complete the remaining base-system upgrade work.
6	pkg update -f pkg upgrade	Refresh package metadata and align installed packages with the new release.
7	freebsd-version -kru	Verify the final system state.

FAQ

Frequently Asked Questions

These are the questions that usually matter once the conversation moves from hobby systems to real production planning.

Can I use this workflow for any FreeBSD version jump?

Use it for supported binary -RELEASE upgrades. If the system is very old, unsupported, or built from source, the planning becomes more involved and you should read the target release notes, installation instructions, and source-upgrade guidance first.

Is -STABLE okay for enterprise because it has “stable” in the name?

No. In FreeBSD terminology, -STABLE is still a development branch. It can be excellent for advanced operators, but it should not be moved into production casually or without real validation.

Why not just stay on an older supported branch as long as it still gets updates?

You can for a short transition window, but once a branch gets close to end-of-life it stops being a comfortable long-term choice. Enterprise planning is better when the support runway is long enough that you are not constantly racing the calendar.

Should new production systems standardize on FreeBSD 14 or 15?

FreeBSD 14 is the more conservative answer today. FreeBSD 15 is appropriate if you have validated your applications and you want to align with the newer major line early. The better choice depends less on marketing and more on your testing, drivers, tooling, and vendor dependencies.

What package repository branch is safer in production?

Quarterly is the safer default because it is meant to provide a more predictable and stable experience. Latest is fine when you intentionally want newer packages and can absorb a faster change rate.

What if something goes wrong during freebsd-update?

FreeBSD documents a rollback capability for the last set of changes with freebsd-update rollback. That is helpful, but it is still not a substitute for good backups and an upgrade rehearsal on non-production systems.

What is the biggest production mistake in a FreeBSD upgrade?

Treating the release number as the whole decision. The real production decision is branch strategy: supported -RELEASE, package branch policy, change window, and whether your team is truly prepared to own a development branch.

When is -CURRENT actually the right answer?

When you are developing on FreeBSD itself, actively testing future changes, or working in a lab that expects breakage and follows the project closely. It is not the normal answer for enterprise operations.

Final thought

A FreeBSD upgrade is not only a version change. It is also a branch choice.

For most production systems, that choice should remain simple: stay on a supported -RELEASE branch, keep packages predictable, and move forward before support windows get short.

Use -STABLE when you truly want to participate in the engineering track. Use -CURRENT when development and experimentation are the goal. For everyone else, supported releases are the branch strategy that is easiest to trust.

Raell Dottin