Synopsis #
The quarterly package branch favors predictable changes. It accepts security fixes, bug fixes, and ports-framework corrections while generally excluding feature updates. A new quarterly branch is cut in January, April, July, and October. The latest branch follows the newest packages produced from the main Ports Collection.
Quarterly is a suitable default for hosts where change control matters more than immediate feature releases. Latest is suitable when applications or desktop hardware support require newer package versions and the additional changes can be reviewed and tested.
The branch is a policy for the repository, not a way to upgrade one application in isolation. See packages, ports, or poudriere when only one package needs custom options or a different build policy.
Inspect the current policy #
Record the effective ABI, repositories, and configuration before editing anything:
$ pkg -vv
$ pkg repositories
Inspect repository files under both /etc/pkg/ and /usr/local/etc/pkg/repos/. Local overrides belong under /usr/local/etc/pkg/repos/; do not edit the release-supplied file in /etc/pkg/.
Also identify repositories for packaged kernel modules. Since FreeBSD 14.3, official kernel-module repositories are release- and ports-branch-specific. A graphics or other out-of-tree kernel module must remain aligned with both the running release and the chosen ports branch.
Select a branch #
| Requirement | Branch |
|---|---|
| Fewer feature changes between maintenance windows | Quarterly |
| Default policy for an ordinary release installation | Quarterly |
| New application or desktop versions are required | Latest |
| A tested fleet already follows the main Ports Collection | Latest |
| A locally checked-out quarterly Ports tree is mixed with packages | The matching quarterly branch |
Do not select latest merely to fix a repository or ABI error. Diagnose that error first with the package mismatch guide .
Change the official ports-package repository #
Create the local repository directory if necessary:
# mkdir -p /usr/local/etc/pkg/repos
To select latest, place this override in /usr/local/etc/pkg/repos/FreeBSD.conf:
FreeBSD-ports: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/latest"
}
To select quarterly instead, use the corresponding branch path:
FreeBSD-ports: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/quarterly"
}
Repository names can differ on an upgraded or locally customized installation. The key in the override must match the repository being overridden; verify it with pkg -vv rather than assuming a name from an example.
Force a catalogue refresh, then review the complete proposed transaction:
# pkg update -f
# pkg upgrade -n
The dry run should show the expected branch transition. Unexpected repository changes, large removals, or many unrelated downgrades require investigation before running pkg upgrade without -n.
Keep ports and packages coherent #
The official Handbook warns against using a main-branch Ports Collection with quarterly binary packages because dependency versions can differ. When both must be used, keep the checked-out ports branch aligned with the binary repository branch.
For durable custom options or a fleet of hosts, build packages from a deliberately selected ports branch with poudriere and let clients use that repository. Avoid an installation that silently alternates between official and private packages.
Review the policy over time #
Record the selected branch with the host’s maintenance documentation. Reconsider it when:
- a quarterly branch changes at the beginning of a calendar quarter;
- the operating system is upgraded;
- a private poudriere repository replaces official packages;
- packaged kernel modules are added;
- an application requirement forces latest.
Changing to latest does not change the base-system release and does not replace the supported-release upgrade policy .