Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Upgrade FreeBSD 12.⋯ to FreeBSD 13


If you want future FreeBSD update and upgrade routines to be simpler: please support the PkgBase initiative. See, for example,

Guidance below is for 12.⋯ systems that:

  • fall below 12.2-RELEASE-p4 (12.2 patch level 4)
  • boot from ZFS (not UFS).

All commands are to be run as root. Beyond step 7 below, aim to run each command in terminal that is away from (or without starting) the desktop environment. Hint:

  • Control-Alt-F2 switches to terminal ttyv1
  • from there, Alt-F9 returns to the desktop environment.

If you never previously followed a freebsd-update(8) routine, please be prepared:

  • to respond appropriately when presented with a colon : or (END) at the command line – with q as the laziest effective response
  • for a possible requirement to use vi(1) for command line edition of some files.

For EFI system partition (ESP) boot loader guidance please see, for example:

The routine

  1. pkg -v
  2. if the package management tool is not yet installed, allow it
  3. pkg query '%R %o %v' | grep -v -e FreeBSD -e ports-mgmt\/pkg | sort > /var/log/exceptionalpackages.txt && cat /var/log/exceptionalpackages.txt
  4. if the query reveals anything (any package that was not installed from a FreeBSD package repository), be aware that the pkg upgrade lines below might not cover what's required for an entirely successful upgrade – be prepared to act upon an on-screen hint to rebuild all installed 3rd party software (e.g., programs installed from the ports tree)
  5. du -h /var/cache/pkg && pkg clean -qy && pkg autoremove -qy && du -h /var/cache/pkg
  6. bectl create 12.2-RELEASE-p6 && bectl activate 12.2-RELEASE-p6
  7. restart the computer
  8. /usr/sbin/freebsd-update fetch install
  9. freebsd-version -kru
  10. observe the mismatch
  11. restart the computer
  12. /usr/sbin/freebsd-update install
  13. – there might be nothing applicable
  14. pkg upgrade
  15. /usr/sbin/freebsd-update install
  16. – there might be nothing applicable
  17. restart the computer
  18. freebsd-version -kru
  19. du -h /var/cache/pkg && pkg clean -qy && pkg autoremove -qy && du -h /var/cache/pkg
  20. bectl create 13.0-RELEASE && bectl activate 13.0-RELEASE
  21. restart the computer
  22. /usr/sbin/freebsd-update upgrade -r 13.0-RELEASE
  23. /usr/sbin/freebsd-update install
  24. freebsd-version -kru
  25. restart the computer
  26. freebsd-version -kru
  27. /usr/sbin/freebsd-update install
  28. freebsd-version -kru
  29. pkg upgrade
  30. /usr/sbin/freebsd-update install
  31. sed -i '' '/opensolaris/d' /boot/loader.conf && cat /boot/loader.conf
  32. restart the computer.


Some of the logic above is drawn from cutting edge Chapter 24 of the FreeBSD Handbook.

freebsd-version(1) lines are optional:

  • for a person who has never previously used freebsd-update, observing the output from freebsd-version might help to understand the state of things at various stages within routines such as this.

Package cleaning and autoremoval lines are optional:

  • intended to help minimise the sizes of past boot environments that might be rarely or never required.

ttyv1 is recommended because (amongst other things) pkg upgrade whilst signed in to a packaged desktop environment might adversely affect the running environment. If you prefer to run the commands in a terminal in a desktop environment, proceed with caution – beware of any running program prematurely loading an upgraded component; refrain from running any additional program; and so on.

The interim boot environment with 12.2-RELEASE-p6 (or greater) is:

  • primarily for a fix to freebsd-update

– if you skip the relevant steps, and if you subsequently find a problem with scripted or manual use of passwd(1) with 12.2-RELEASE-p3 (or less), you may:

Hint: possible symptoms of a passwd-related problem include pkg install falkon failing at or around the mysql57-server stage.

Use of vi is avoidable:

  • permanently set EDITOR and VISUAL variables to /usr/local/bin/nano

– I have a GitHub gist for this, but it's not public.

Exceptions for users of helloSystem

You must:

  • pkg lock hello

If not already locked, this is to safeguard essential helloSystem files that are associated with the non-ported hello package, which has a nonconformist origin and a name that conflicts with a previously packaged port (misc/hello, unrelated to helloSystem).

Without the lock, pkg upgrade will replace helloSystem's ambiguous hello < 2.10_1 with properly-defined misc/hello 2.10_1. Replacement is proper – given the version numbers – however the consequences are unwanted. Related:

In addition, if you find helloSystem preventing normal use of pkg(8), you should:

  • mv /usr/sbin/pkg.real /usr/sbin/pkg

– for the non-standard pkg to be replaced by the real (FreeBSD-provided) package management tool.

Copy link

grahamperrin commented Mar 7, 2021

Copy link

Tycho-S commented Apr 13, 2021

Will you update this excellent guide for the release version? Or does the same apply?

Copy link

grahamperrin commented Apr 16, 2021

Thank you – I wrote 13.0-RELEASE into the file a few days ago (see Revisions).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment