FreeBSD Package Management: Complete pkg Reference (2026)

pkg is the binary package manager for FreeBSD. It handles installation, upgrades, dependency resolution, vulnerability auditing, and repository management for prebuilt packages. If you use FreeBSD, you use pkg. This is the complete reference.

For the comparison between binary packages and building from ports, see pkg vs ports on FreeBSD. For system updates (base system, not packages), see FreeBSD Update Guide.

Bootstrap and Initial Setup

On a fresh FreeBSD install, pkg bootstraps itself on first use:

sh
# First run triggers bootstrap
pkg info
# Responds with: "pkg is not installed. Do you want to fetch and install it? [y/N]"
# Answer y

# Or install explicitly
pkg bootstrap -f

After bootstrap, verify:

sh
pkg --version
pkg -vv  # Shows configuration, repositories, and directories

Core Commands

Installing Packages

sh
# Install a single package
pkg install nginx

# Install multiple packages
pkg install nginx postgresql16-server redis

# Install without confirmation prompt
pkg install -y vim

# Install a specific version (if available in the repo)
pkg install python311

# Dry run -- show what would be installed without doing it
pkg install -n firefox

Removing Packages

sh
# Remove a package
pkg delete nginx

# Remove a package and its unused dependencies
pkg delete -R nginx

# Remove without confirmation
pkg delete -y nginx

# Dry run
pkg delete -n nginx

Autoremove

Remove packages that were installed as dependencies but are no longer needed:

sh
# Show what would be removed
pkg autoremove -n

# Remove orphaned dependencies
pkg autoremove -y

Upgrading

sh
# Update the package repository catalog
pkg update

# Upgrade all installed packages
pkg upgrade

# Upgrade a specific package
pkg upgrade nginx

# Dry run -- show what would change
pkg upgrade -n

# Force upgrade (reinstall even if same version)
pkg upgrade -f

Searching

sh
# Search by package name
pkg search nginx

# Search with description
pkg search -D "web server"

# Search by exact name
pkg search -e nginx

# Show full information for search results
pkg search -f nginx

# Search by origin (category/port)
pkg search -o www/nginx

Information

sh
# Show information about an installed package
pkg info nginx

# Show all installed packages
pkg info

# Show dependencies of a package
pkg info -d nginx

# Show reverse dependencies (what depends on this package)
pkg info -r openssl

# Show files installed by a package
pkg info -l nginx

# Show which package owns a file
pkg which /usr/local/sbin/nginx

# Show package options (compile-time options)
pkg info -o nginx

# Show total number of installed packages
pkg info | wc -l

Package Statistics

sh
# Show disk space used by installed packages
pkg stats

# Show package sizes
pkg info -s nginx

# List packages sorted by size
pkg info -sa | sort -k2 -h

Repository Management

Default Repository

FreeBSD ships with the official package repository configured. The configuration lives in /etc/pkg/FreeBSD.conf (system default) and can be overridden in /usr/local/etc/pkg/repos/.

sh
# View repository configuration
pkg -vv | grep -A 5 "Repositories"

# Update repository catalog
pkg update

# Force catalog update
pkg update -f

Repository Configuration

sh
# View the default repo config
cat /etc/pkg/FreeBSD.conf

To use the latest package branch instead of quarterly:

sh
mkdir -p /usr/local/etc/pkg/repos

cat > /usr/local/etc/pkg/repos/FreeBSD.conf << 'CONF'
FreeBSD: {
    url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest"
}
CONF

# Update after changing repos
pkg update -f

The two branches:

quarterly: Updated every quarter. Packages receive security fixes but not version bumps. More stable.
latest: Tracks the most recent port builds. Newer versions, but more likely to have upgrade issues.

Custom Repositories

For Poudriere-built packages or third-party repos:

sh
cat > /usr/local/etc/pkg/repos/custom.conf << 'CONF'
custom: {
    url: "http://pkg.example.com/packages/${ABI}",
    enabled: yes,
    priority: 10
}
CONF

Higher priority numbers take precedence. If a package exists in multiple repos, the highest-priority repo wins.

Disabling the Default Repository

If you run your own Poudriere repo and want to use only your packages:

sh
cat > /usr/local/etc/pkg/repos/FreeBSD.conf << 'CONF'
FreeBSD: {
    enabled: no
}
CONF

Security Auditing

sh
# Check installed packages for known vulnerabilities
pkg audit -F
# -F fetches the latest vulnerability database first

# Just check without updating the database
pkg audit

# Show detailed vulnerability information
pkg audit -F -r

Set up automatic auditing:

sh
# Add to /etc/periodic.conf
echo 'daily_status_security_pkgaudit_enable="YES"' >> /etc/periodic.conf

# This runs during the daily periodic job and emails results to root

Package Locking

Prevent specific packages from being upgraded or removed:

sh
# Lock a package
pkg lock nginx

# Lock multiple packages
pkg lock nginx postgresql16-server

# Show locked packages
pkg lock -l

# Unlock a package
pkg unlock nginx

# Unlock all packages
pkg unlock -a

Use cases for locking:

A newer version breaks your application
You compiled a custom version from ports and do not want pkg to overwrite it
A critical service depends on a specific version

Annotations and Metadata

sh
# Add a custom annotation to a package
pkg annotate -A nginx custom_note "Compiled with custom modules"

# Show annotations
pkg annotate -S nginx custom_note

# Delete an annotation
pkg annotate -D nginx custom_note

Package Files and Integrity

sh
# Verify installed package checksums
pkg check -s -a

# Check for missing dependencies
pkg check -d -a

# Reinstall packages with missing files
pkg check -r -a

# Show which package owns a file
pkg which /usr/local/bin/python3.11

# Find files that do not belong to any package
pkg query -e '%#F = 0' %n

Advanced Operations

Holding Back Specific Packages During Upgrade

sh
# Lock packages you do not want upgraded
pkg lock specific-package

# Run the upgrade
pkg upgrade

# Unlock after
pkg unlock specific-package

Reinstalling Packages

sh
# Reinstall a single package
pkg install -f nginx

# Reinstall all packages (nuclear option -- use after major version upgrade)
pkg upgrade -f

Creating Package Archives

sh
# Create a package file from an installed package
pkg create nginx
# Creates nginx-<version>.pkg in the current directory

# Create all installed packages
pkg create -a -o /path/to/output/

# Useful for offline installation or backup

Installing from a Local File

sh
# Install a .pkg file directly
pkg add /path/to/nginx-1.24.0.pkg

# Install from a URL
pkg add https://example.com/packages/custom-tool-1.0.pkg

Fetching Without Installing

sh
# Download a package and its dependencies without installing
pkg fetch -d nginx

# Downloaded packages go to /var/cache/pkg/

Cleaning the Cache

sh
# Remove cached packages that are no longer in the repo
pkg clean

# Remove all cached packages
pkg clean -a

# Show cache size
du -sh /var/cache/pkg/

Poudriere Integration

Poudriere is the FreeBSD port build system. It builds binary packages from the ports tree in clean jails. Using Poudriere lets you customize port options and build your own package repository.

Basic Poudriere Setup

sh
# Install Poudriere
pkg install poudriere

# Create a ports tree
poudriere ports -c -p default

# Create a build jail
poudriere jail -c -j 14amd64 -v 14.2-RELEASE -a amd64

# Create a package list
cat > /usr/local/etc/poudriere.d/pkglist << 'LIST'
www/nginx
databases/postgresql16-server
databases/redis
editors/vim
shells/zsh
security/sudo
LIST

# Build packages
poudriere bulk -j 14amd64 -p default -f /usr/local/etc/poudriere.d/pkglist

Serving Poudriere Packages

sh
# Packages are built to:
# /usr/local/poudriere/data/packages/14amd64-default/

# Serve with a simple HTTP server or nginx
# Point your custom repo config to this directory

cat > /usr/local/etc/pkg/repos/poudriere.conf << 'CONF'
poudriere: {
    url: "file:///usr/local/poudriere/data/packages/14amd64-default",
    enabled: yes,
    priority: 100
}
CONF

pkg update -f

Custom Port Options

sh
# Set options for a specific port
poudriere options -j 14amd64 -p default www/nginx

# Set options for all ports in your list
poudriere options -j 14amd64 -p default -f /usr/local/etc/poudriere.d/pkglist

# Build with custom options
poudriere bulk -j 14amd64 -p default -f /usr/local/etc/poudriere.d/pkglist

Configuration File Reference

/usr/local/etc/pkg.conf

Global pkg configuration:

sh
cat > /usr/local/etc/pkg.conf << 'CONF'
# Assume yes for all confirmations
ASSUME_ALWAYS_YES = false;

# Package cache directory
PKG_CACHEDIR = "/var/cache/pkg";

# Default yes for prompts
DEFAULT_ALWAYS_YES = false;

# Number of parallel fetches
FETCH_RETRY = 3;

# Autoclean cache after install
AUTOCLEAN = false;

# Trigger on events
ALIAS: {
    all-depends: "query %dn-%dv",
    annotations: "info -A",
    provided: "query %Fp",
}
CONF

Useful pkg Aliases

Add to /usr/local/etc/pkg.conf:

sh
ALIAS: {
    # Show all leaf packages (not depended on by anything)
    leaves: "query -e '%#r = 0' '%n-%v'",

    # Show package size on disk
    size: "info -s",

    # Show recently installed packages
    recent: "query -e '%t > 0' '%t %n-%v' | sort -rn | head -20",
}

Troubleshooting

Repository Catalog Errors

sh
# Force a clean catalog update
pkg update -f

# If that fails, remove the catalog and retry
rm -rf /var/db/pkg/repo-FreeBSD*
pkg update

Dependency Conflicts

sh
# Show what conflicts exist
pkg check -d -a

# Force resolution (reinstall missing deps)
pkg install -f problematic-package

# Nuclear option: reinstall all packages
pkg upgrade -f

pkg Database Corruption

sh
# Back up the current database
cp /var/db/pkg/local.sqlite /var/db/pkg/local.sqlite.bak

# Rebuild the database from installed packages
pkg-static install -f pkg

Disk Space Issues

sh
# Clean the package cache
pkg clean -a

# Find largest installed packages
pkg info -sa | sort -k2 -h | tail -20

# Remove packages you no longer need
pkg autoremove

ABI Mismatch After OS Upgrade

After a major FreeBSD version upgrade (e.g., 13.x to 14.x):

sh
# Reinstall pkg itself first
pkg-static install -f pkg

# Then force-upgrade all packages
pkg upgrade -f

Package Signature Errors

sh
# If you see "signature verification failed":
# 1. Check your system clock
ntpdate pool.ntp.org

# 2. Force update the catalog
pkg update -f

# 3. If using a custom repo, verify the signing key

Quick Reference Cheat Sheet

sh
# Install
pkg install <name>

# Remove
pkg delete <name>

# Search
pkg search <name>

# Info
pkg info <name>

# Upgrade all
pkg update && pkg upgrade

# Audit for vulnerabilities
pkg audit -F

# Clean cache
pkg clean -a

# Remove orphans
pkg autoremove

# Lock version
pkg lock <name>

# Which package owns a file
pkg which /path/to/file

# Verify package integrity
pkg check -s -a

FAQ

What is the difference between pkg and ports?

pkg installs precompiled binary packages. Ports compile software from source with customizable options. Use pkg for standard installations. Use ports when you need custom compile-time options, newer versions, or software not available as a binary package.

Should I use the quarterly or latest branch?

Quarterly for production servers -- it is more stable and receives fewer disruptive changes. Latest for desktops or development environments where you want the newest software versions.

How do I switch from quarterly to latest?

sh
mkdir -p /usr/local/etc/pkg/repos
cat > /usr/local/etc/pkg/repos/FreeBSD.conf << 'CONF'
FreeBSD: {
    url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest"
}
CONF
pkg update -f
pkg upgrade

Can I mix packages from pkg and ports?

Yes, but with caution. A port-installed package will be tracked by pkg. If the pkg repository has a different version, pkg upgrade may overwrite your port-built version. Use pkg lock to prevent this.

How do I downgrade a package?

pkg does not support downgrade directly. Options:

Install a specific version if available: pkg install package-1.2.3
Lock the package at the current version: pkg lock package
Build the desired version from ports with Poudriere

How often should I run pkg audit?

Daily. Configure it in /etc/periodic.conf for automatic checks. Security vulnerabilities in installed software are the most common attack vector.

How do I see what changed in a package upgrade?

sh
# Before upgrading, check what will change
pkg upgrade -n

# After upgrading, check the package log
cat /var/log/messages | grep pkg

What does pkg autoremove actually remove?

Packages that were installed automatically as dependencies and are no longer required by any manually-installed package. It is safe to run. Always check with pkg autoremove -n first if you are unsure.