Upgrading FreeBSD With Pkgbase

Firstly, this is being written December 11, 2025. I suspect that the issue will go away soon. I'm putting this up in case it takes awhile to completely fix things.

As most FreeBSD users know by now, freebsd-update is being replaced by pkgbase, which will upgrade both packages and the base system. There's lots of places to get more information, but I'm sending anyone looking for more information to Vermaden's article about it. To use it to upgrade 14.x to 15 is not officially supported, but is surprisingly simple if you use pkgbasify, a lua script that will convert your 14.x system to be able to use pkgbase.

Judging from FreeBSD forums, a few things are giving people trouble. This is an effort to get the instructions in one place, though as mentioned above, I think it will be fixed soon.

The handbook has a section on using it to update to 15.0 here, but there are a couple of things that have to, at time of writing this article, be updated. So, going through the steps, if your system is on ZFS, you make a boot environment, mount it, and install into that. If it works, you can make it the default. I am giving the handbook steps, with some minor changes.

First if on ZFS, make a backup. You should do that anyway, but it's easiest on ZFS. All commands will have to be run as root or with root privilege, using doas or sudo. You can call the backup whatever you wish, I usually call it working with the date. I'm also going to create a new boot environment for the updated system. We'll call that one 15.0-RELEASE. We'll make a directory for the upgrade and mount it. 
bectl create working-$(date +%F)
bectl create 15.0-RELEASE
mkdir /mnt/upgrade
bectl mount 15.0-RELEASE /mnt/upgrade

If you used the pkg basify script, you should already have /usr/local/etc/pkg/repos/FreeBSD-base.conf. If you don't, then create it. It should read 
FreeBSD-base {
    url = "pkg+https://pkg.freebsd.org/${ABI}/base_release_0";
    mirror_type = "srv";
    signature_type = "fingerprints";
    fingerprints = "/usr/share/keys/pkg";

This is probably what the pkgbasify script made, and is what the handbook suggests, but DO NOT USE IT, we're going to fix it shortly. The problem is that the fingerprints line points to the wrong version of pkg keys, so we'll have to fix that. The solution is in 15.0's release notes. There is more explanation there, but the main thing is that you have to get the most current pkg keys.

I use gitup to get source code. So, if you don't have gitup, you cam install it, or use whatever method you prefer to checkout the source code. In this example, though, I'm using gitup.

Edit /usr/local/etc/gitup.conf. Look for the stanza beginning with "release". It will say 14.0 or something like that, maybe 14.3. Change the "branch" line so that it reads 15.0. Now you can just get the source code with 
gitup release

Now as it says in the release notes run 
cp -R /usr/src/share/keys/pkgbase-15 /usr/share/keys/pkgbase-15

Edit the fingerprints line in /usr/local/etc/pkgs/repos so that it reads 
fingerprints = "/usr/share/keys/pkgbase-15";

Now that this is done, we can go back to the handbook's instructions. 
env ABI=FreeBSD:15:amd64 pkg-static -c /mnt/upgrade upgrade -r FreeBSD-base

You should see something like 
Newer FreeBSD version for package FreeBSD-zoneinfo:
To ignore this error set IGNORE_OSVERSION=yes
- package: 1500058
- running userland: 1500000
Ignore the mismatch and continue? [y/N]:

Choose y and the system should update.

The rest of this is taken directly from the handbook. Confirm that the update was successful. 

chroot /mnt/upgrade
freebsd-version -ku
exit

Hopefully it will say FreeBSD-15.0-RELEASE. Temporarily activate the boot environnment for 15 and reboot. 
bectl activate -t 15.0-RELEASE
shutdown -r now

If all seems to be working on the reboot, you can now make the 15.0 boot environment permanent. 
bectl activate 15.0-RELEASE

Now, when you reboot, it will automatically use the 15.0 system.

Thanks to the many people who posted on the forums, and especially to SirDice, a moderator there, who pointed me to the release notes that gave me the solution. Any mistakes are, of course, my own.