Procedure for upgrading and auditing installed packages using the built-in pkg interface in FreeBSD. Tested on FreeBSD 14.2 on 2025-04-04.
What are packages on FreeBSD?
Packages are applications, that has been precompiled with a default set of options. The packages are tested to work with the current version FreeBSD and the current packages in the repository. Upgrading of packages is done with the built-in pkg interface.
# man pkg
Below is a an example of the typical minimum series of commands for upgrading installed packages. However, I recommend, that the full procedure on this page is followed.
# pkg upgrade
# pkg autoremove
# pkg clean
# find /var/db/fre*/files -type f -mtime +7d -print -delete
# reboot
Determining version and patch level of FreeBSD.
Confirm, that you are running the current version and patch level of FreeBSD. The built-in freebsd-version utility can determine the installed, running and userland version and patch level of FreeBSD. These should all match, but it is not uncommon, that userland is different.
# freebsd-version -k -r -u
If the version and patch level of FreeBSD is not up to current, you should upgrade the FreeBSD base system before upgrading packages. Read more about this in How to upgrade to new minor and major releases of FreeBSD.
Configuring package repository for FreeBSD.
FreeBSD is by default configured to install packages from an official FreeBSD repository. If you want FreeBSD to install from another package repository, you can configure this. You might want to use another branch of packages. You might have compiled your own packages with Poudriere.
In this example, the default FreeBSD repository is disabled and a custom local Poudriere repository is enabled.
# mkdir -p /usr/local/etc/pkg/repos
# nano /usr/local/etc/pkg/repos/freebsd.conf
FreeBSD: {
url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest",
enabled: no
}
# nano /usr/local/etc/pkg/repos/wopr.conf
WOPR: {
url: "file:///usr/local/poudriere/data/packages/1402-release-amd64-latest-desktop",
mirror_type: "none",
enabled: yes
}
Updating the FreeBSD repository catalogue.
Updating the packages in the FreeBSD repository catalogue will read the newest packages and update the catalogue accordingly. If omitted, this should happen automatically, when upgrading. If you configured a new repository, this should show up at this stage.
# pkg update -f
Locking and unlocking packages.
If there is a missing dependency or other temporary issue upstream, that will cause one or more important packages to be removed, when upgrading the installed packages, then this can be avoided by using the lock feature in pkg. An issue like this happens more often, when Poudriere is used to build more recently updated source code, such as the latest ports branch.
# pkg lock signal-desktop
The currently locked packages can be listed.
# pkg lock -l
Currently locked packages:
signal-desktop-7.46.0_1
When the issue has been resolved, the packages can be unlocked and upgrading can be performed again.
# pkg unlock signal-desktop
Upgrading installed packages.
Update the installed packages. If a package or dependency is no longer available, such as a temporary issue upstream, one or more important packages might be removed. This can be avoided by a temporary lock of a package.
# pkg upgrade
Auditing installing packages.
You might want to audit the installed packages against known vulnerabilities.
# pkg audit -F
If major OS version upgrade is detected.
# pkg update -f pkg: Warning: Major OS version upgrade detected. Running "pkg bootstrap -f" recommended pkg: Repository FreeBSD has a wrong packagesite, need to re-create database
The current pkg interface must be changed to match the new version of FreeBSD. This is done by bootstrapping the pkg interface, which will then automatically download and reinstall – all – applications, when upgrading is started.
# pkg bootstrap -f # pkg update -f # pkg upgrade
If upgrading failed or applications no longer work.
I have experienced, that larger desktop computers can break after an upgrade of packages. You should read into error messages on the console and in the logs and try to pin point the actual cause of the problem and look to solve that. The members of The FreeBSD Forums are very kind and competent.
However it is also my experience, that some of the error messages, that are produced, can lead to many forum discussions with more or less helpful solutions. An example is the following failed upgrade, that had an error message about installing files into the same place.
[4/285] Installing librsvg2-rust-2.50.2… pkg: librsvg2-rust-2.50.2 conflicts with librsvg2-2.40.21 (installs files into the same place). Problematic file: /usr/local/bin/rsvg-convert
This problem, as well as other related problems, was solved by issuing a rebuild of all installed packages with the static version of pkg, which is known from upgrading the base system. The reason, that pkg-static is used instead of pkg is, that pkg-static uses static linked libraries, while pkg depends on dynamically linked libraries, which might break during the rebuild.
# pkg-static install -f pkg # pkg-static upgrade -f
Removing unused dependencies.
You should always remove dependencies, that are no longer required by other packages. This kind of packages are also known as leaf dependencies. The pkg interface will list leaf dependencies before removing them.
# pkg autoremove
Clearing local cache of fetched packages.
You should clear the local cache of fetched remote packages. This is relevant, if you have limited storage space.
# pkg clean
Deleting old packages sources.
You should delete package sources, because they can take up a lot of disk space over time. In this example, the last 7 days are kept.
# find /var/db/fre*/files -type f -mtime +7d -print -delete
Rebooting FreeBSD.
If this upgrade was performed on a server or other critical production system, then a reboot and test of services is recommended.
In the following example, your command history will be saved and users will have some time to exit properly.
# shutdown -r +30s
# exit
In the following example, the system rebooted right away. Your command history will be lost.
# reboot
If upgrading was succesful.
The installed packages on your FreeBSD system has now been upgraded.
More about updating FreeBSD.
⧐ How to upgrade to new minor and major releases of FreeBSD.
⧐ How to update (patch) the FreeBSD system.