The Handbook

    Theme
    • Guides
        • Check a system before installing FreeBSD
        • Orient a Linux administrator on FreeBSD
        • Supported FreeBSD releases
        • Choose a FreeBSD documentation and support channel
        • Move files safely without GNU mv -t
        • Update and Upgrade FreeBSD
        • Upgrade 14.4 or 15.0 to FreeBSD 15.1
        • Choose packages, ports, or poudriere
        • Choose the quarterly or latest package branch
        • Choose a FreeBSD download or package mirror
        • Convert a test installation to pkgbase
        • Make a system setting persistent
        • Run a command from cron reliably
        • Configure locale, keyboard, and time zone
        • Configure a serial console for recovery
        • Choose a custom kernel, module, or loader setting
        • Run a Linux binary with the compatibility layer
        • Check desktop and laptop hardware before installation
        • Choose and check a graphics driver
        • Choose Xorg or Wayland
        • Build a maintainable desktop baseline
        • Install and check a desktop browser
        • Install GNOME and troubleshoot graphical login
        • Check laptop Wi-Fi, power, and suspend
        • Check multimedia readiness
        • Choose and configure a printing stack
        • Run Windows applications with Wine
        • Snapshot and replicate a ZFS dataset
        • Choose a filesystem and storage layout
        • Operate ZFS without losing the recovery path
        • Restore files from a ZFS snapshot
        • Find what is using ZFS space
        • Grow a ZFS virtual disk
        • Read ZFS pool health and run a scrub
        • Replace a failed device in a ZFS mirror
        • Replicate a ZFS dataset over SSH
        • Test changes in a writable ZFS clone
        • Read a ZFS pool from another FreeBSD system
        • Change PF safely on a remote host
        • Configure a narrow WireGuard tunnel
        • Share a directory with NFS
        • Share files with a named Samba account
        • Plan a FreeBSD home server
        • Choose a mail server or an outgoing relay
        • Publish a network service safely
        • Choose a jail network model
        • Choose native jails or a jail manager
        • Choose a jail or a bhyve virtual machine
        • Establish a FreeBSD security baseline
        • Choose a MAC policy
        • Audit security-relevant activity
        • Start a DTrace performance investigation
    • Integrations
        • Create a first jail with Bastille
        • Compare jail managers and OCI tooling
        • Publish a Bastille service through PF
        • Mount a ZFS dataset in a Bastille jail
        • Update and upgrade Bastille jails
        • Back up and restore a Bastille jail
        • Prepare bhyve and vm-bhyve
        • Install a Linux guest with vm-bhyve
        • Choose NFS or Samba for file sharing
        • Choose ZFS backup automation
        • Build a first signed poudriere repository
        • Operate a signed poudriere repository
        • Manage FreeBSD configuration with Ansible or Salt
        • Run Motion with webcamd on FreeBSD
        • Design a reverse proxy, certificates, and monitoring
    • FAQ
      • Troubleshooting
          • Recover an interrupted freebsd-update run
          • Resolve a package repository or ABI mismatch
          • Diagnose the FreeBSD boot path
          • Recover with a ZFS boot environment
          • Diagnose DNS, routing, and firewall paths
          • Diagnose network mbuf exhaustion
          • Bind a service to a low port without running it as root
          • Diagnose a service that will not start
          • Diagnose audio output or input
          • Diagnose webcamd, cuse, and a webcam
          • Fix USB device permissions without opening every device
      • About this handbook
      • Synopsis
      • Check the starting point
      • Run the conversion
      • Check configuration and reboot
      • References

      Convert a test installation to pkgbase

      Last reviewed
      21 November 2026
      Applies to
      15.1-RELEASE
      Tested on
      15.1-RELEASE

      Synopsis #

      Pkgbase manages the kernel and base userland through pkg. It is a technology preview in FreeBSD 15. Use a disposable installation or a restorable copy for a first conversion; conversion can leave an unbootable system if it fails.

      This procedure uses the FreeBSD Foundation’s pkgbasify helper. It converts a traditional installation; it is not needed if base files are already registered as packages.

      Check the starting point #

      Have a working console, installation media, and a backup stored outside this system. A ZFS boot environment helps with rollback but does not replace that backup.

      $ freebsd-version -kru
      # pkg bootstrap
      $ pkg which /usr/bin/uname
      $ df -h / /usr /var
      # pkg repositories
      

      If pkg which reports a FreeBSD-runtime package, the system already uses pkgbase. Follow base-system maintenance instead.

      Keep at least 5 GiB free for conversion, including space on the filesystems that hold base files. Read the helper’s current instructions and known problems before proceeding. Check separate datasets mounted over base directories, especially a read-only /var/empty or a separate /root, against those known problems.

      Run the conversion #

      As root, download and inspect the helper before running it:

      # fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkgbasify.lua
      # less pkgbasify.lua
      # chmod +x pkgbasify.lua
      # ./pkgbasify.lua
      

      Accept the backup boot-environment prompt on a ZFS system. The helper selects the release repository and package sets for the installed components, registers base packages, and reinstalls their files. It can merge configuration files and restart SSH, so retain console access until verification is complete.

      If conversion stops with an error, read that error before doing anything else. Do not reboot or repeatedly force installation while the system is only partly converted. Follow the helper’s recovery instructions for the actual failure.

      Check configuration and reboot #

      Confirm the expected users and groups are present and that administrative access still works. Review /etc/ssh/sshd_config and unresolved configuration merges:

      # find /etc -name '*.pkgnew' -print
      # sshd -t
      # pkg which /usr/bin/uname
      # pkg info -x '^FreeBSD-'
      

      Resolve any .pkgnew files before rebooting. Test a new administrative login while the original console remains open, then reboot:

      # shutdown -r now
      

      After boot, check the running kernel, installed userland, network, and required services. Use pkgbase maintenance for later base updates; do not continue using freebsd-update on the converted installation.

      References #

      • FreeBSD documentation: pkgbase
      • pkgbasify instructions and recovery notes
      • Recover using a boot environment

      Independent documentation. Not affiliated with or endorsed by the FreeBSD Project or the FreeBSD Foundation.

      Report a bug
      • Synopsis
      • Check the starting point
      • Run the conversion
      • Check configuration and reboot
      • References