Synopsis #
Most systems should install third-party software as binary packages with pkg. The Ports Collection is useful when an individual port needs non-default build options. Poudriere is the maintainable choice when several systems need custom packages, a private repository, or repeatable builds.
These methods use the same ports metadata, but they are not interchangeable at every point in a system’s life. Choose one source of packages deliberately and keep its branch, architecture, and build options coherent.
Choose the workflow #
| Requirement | Preferred workflow | Reason |
|---|---|---|
| Ordinary server or workstation | Official packages with pkg | Fast installation and the least local maintenance |
| Predictable production changes | Quarterly package branch | Security and bug fixes with fewer feature changes |
| Newer application versions | Latest package branch | Faster access to updates, with more change to review |
| One local build with a special option | Ports Collection | Direct control over that port’s build options |
| Custom options on several hosts | Poudriere repository | Isolated, repeatable builds delivered as packages |
| Offline or controlled package source | Poudriere repository | One approved repository can serve multiple clients |
Do not compile an application merely because source is available. A local build consumes time, disk space, and maintenance attention. Prefer the official package unless a documented requirement rules it out.
Inspect the current package source #
List configured repositories and the packages visible through them:
$ pkg -vv
$ pkg repositories
$ pkg search -x '^nginx$'
pkg -vv can contain more detail than is useful for routine output. The repository configuration is the important part: confirm which repository is enabled before changing branches or installing packages.
The official ports-package repository uses the quarterly branch by default. The latest branch provides newer versions. Changing branches is a repository policy change, not an isolated upgrade of one package. Review the resulting transaction before accepting it:
# pkg update -f
# pkg upgrade
The exact repository configuration file should follow the current FreeBSD Handbook package branch procedure
. Do not edit /etc/pkg/FreeBSD.conf; place local overrides beneath /usr/local/etc/pkg/repos/ so base-system updates do not replace them.
The quarterly or latest decision guide covers branch selection, the local override, kernel-module alignment, and a dry-run review. An existing ABI or catalogue error should first be classified with the package repository and ABI troubleshooting guide .
Use a port for an exceptional local build #
Install or update the Ports Collection by one of the methods documented for the installed release. Inspect the available options before starting a build:
# cd /usr/ports/category/port
# make config
Building and installing from the live Ports Collection can introduce dependencies with options that differ from the packages already installed. Before proceeding, determine whether the resulting dependency set will remain compatible with the configured package repository.
Routine package upgrades can later replace a locally built package. If the custom option must remain in force, a poudriere repository is usually less fragile than repeatedly rebuilding the port on the host.
Use poudriere for a maintained custom repository #
Poudriere builds ports inside clean jails and produces packages that clients install with pkg. It separates compilers and build dependencies from production hosts and records the repository as a repeatable operating-system component.
A poudriere deployment needs explicit decisions about:
- The FreeBSD release and architecture represented by each build jail.
- The Ports Collection branch or commit used for builds.
- The package options and make configuration under version control.
- Repository signing, transport, and client configuration.
- A rebuild and publication schedule for security fixes.
Follow the FreeBSD Handbook poudriere procedure for the initial build environment, then use Operate a signed poudriere repository to define signing, atomic publication, client trust, and rollback boundaries.
Avoid an incoherent package set #
Mixing package sources is not automatically wrong, but it creates an obligation to keep their ABIs, dependency versions, origins, and build options compatible. Warning signs include:
- a transaction proposes an unexpected large removal;
- installed packages alternate between official and private repositories;
- a locally compiled library has options that its packaged consumers did not expect;
- the package branch changes without a full review of the upgrade plan.
Stop before confirming such a transaction. Save the proposed output, inspect repository priority and package origins, and correct the source policy first.