PKG.CONF(5) FreeBSD File Formats Manual PKG.CONF(5)
NAME
pkg.conf - system-wide configuration file for pkg(8)
DESCRIPTION
pkg.conf is the system-wide configuration file used by the pkg(8) tools.
The default location of this file is /usr/local/etc/pkg.conf.
Lines in the file beginning with a "#" are comments and are ignored.
The file is in UCL format. For more information on the syntax of UCL,
please visit the official UCL website -
http://github.com/vstakhov/libucl.
The following types of options are recognized - boolean, string and list
options.
A boolean option is marked as enabled if one of the following values is
specified in the configuration file - YES, TRUE and ON.
OPTIONS
The following options can be defined in pkg.conf:
ABI: string The ABI of the package you want to install, for example
`FreeBSD:14:amd64'. This should be set in combination with
the OSVERSION option if targeting FreeBSD to specify the
exact target version. Default: derived based on ABI_FILE.
ABI_FILE: string
Set the file used to determine the target ABI. Default:
/usr/bin/uname, or if not found, /bin/sh.
ALIAS: key/value list
Define local aliases for various pkg(8) standard command
lines. Whenever the key text occurs as a separate `action'
word in a command line of the form pkg key ..., substitute
the value text verbatim. The replacement can consist of any
sequence of text, which should form a syntactically correct
pkg(8) command line when substituted in and followed by any
remaining tokens from the original command line. Default:
not set.
AUTOCLEAN: boolean
Automatically cleanout the content of PKG_CACHEDIR after
each non dry-run call to pkg-install(8) or pkg-upgrade(8).
Default: NO.
AUTOREMOVE: boolean
Automatically remove orphaned packages after each non dry-
run call to pkg-install(8), pkg-delete(8) or pkg-upgrade(8).
This is equivalent to running pkg-autoremove(8) after each
operation. Default: NO.
DEFAULT_ALWAYS_YES: boolean
When this option is enabled pkg(1) will default to "yes" for
all questions which require user confirmation before doing
anything. Default: NO.
ASSUME_ALWAYS_YES: boolean
When this option is enabled pkg(1) will automatically assume
"yes" to all questions which require user confirmation
before doing anything, as if the -y flag was specified.
Default: NO.
BACKUP_LIBRARIES: boolean
If set to true and if an upgrade will remove a library
(typically due to the library version number having been
bumped), then pkg(8) will back up the library to the path
defined by BACKUP_LIBRARY_PATH. A package containing the
backed up library will be created. This package is named
after the original package containing the library, with the
suffix `-backup-libraries' appended. The package version
will be bumped whenever an additional library is backed up.
Default: NO.
BACKUP_LIBRARY_PATH: string
Path for library backups. Default:
/usr/local/lib/compat/pkg.
COMPRESSION_FORMAT: string
Set the default compression format: tzst, txz, tbz, tar.
Default: tzst.
COMPRESSION_LEVEL: integer
Set the default compression level, special values are:
0 default value per libarchive developers
-1 default value per pkg developers (default)
COMPRESSION_THREADS: integer
Set the number of threads to use during compression and
decompression (only functional for txz and tzst). Default:
-1 (automatic).
CONSERVATIVE_UPGRADE: boolean
Ensure in multi repository mode that the priority is given
as much as possible to the repository where a package was
first installed from. Default: YES.
CUDF_SOLVER: string
Experimental: tells pkg to use an external CUDF solver.
Default: not set.
CASE_SENSITIVE_MATCH: boolean
Match package names or regular expressions given on the
command line against values in the database in a case
sensitive way. Default: YES.
DEBUG_LEVEL: integer
Incremental values from 1 to 4 produce successively more
verbose debugging output. A setting of 0 disables debugging
output. Overridden by the -d command line option. Default:
0.
DEBUG_SCRIPTS: boolean
Activate debug mode for scripts (aka set -x) Default: NO.
DEVELOPER_MODE: boolean
Makes certain errors immediately fatal. Adds various
warnings and suggestions to the output of pkg(1) as an aid
to port maintainers, including indicating when the port
might be marked as architecture independent. Default: NO.
DOT_FILE: string
When defined to a valid path, pkg will generate a dot(1)
file with the dependency graph of the concerned transaction.
EVENT_PIPE: string
Send all event messages to the specified FIFO or Unix
socket. Events messages should be formatted as JSON.
Default: not set.
FETCH_RETRY: integer
Number of times to retry a failed fetch of a file against a
given server before moving on to the next server. For
repositories configured with mirror_type srv or http, each
server in the list is tried this many times before advancing
to the next one; the list is walked at most once. For a
plain repository (a single server) this is the total number
of retries before giving up. Default: 3.
FETCH_TIMEOUT: integer
Maximum number of seconds to wait for any one file to
download from the network, either by SSH or any of the
protocols supported by fetch(3) functions. Default: 30.
HANDLE_RC_SCRIPTS: boolean
When enabled, this option will automatically perform
start/stop of services during package installation and
deinstallation. Services are only started on installation
if they are enabled in /etc/rc.conf. Default: NO.
HTTP_USER_AGENT: string
Define User-agent to be sent to HTTP server when getting
repository data. Default: pkg/<version>.
IGNORE_OSMAJOR: boolean [FreeBSD specific]
Ignore FreeBSD major OS version check. This suppresses the
"Major OS version upgrade detected" warning, useful when
building packages or images for a different OS version than
the host. Default: NO.
IGNORE_OSVERSION: boolean [FreeBSD specific]
Ignore FreeBSD OS version check, useful on -STABLE and
-CURRENT branches. Default: NO.
INDEXDIR: string
If set, the directory to search for INDEXFILE in. If unset,
PORTSDIR will be searched instead. Default: not set.
INDEXFILE: string
The filename of the ports index, searched for in INDEXDIR or
PORTSDIR. Default: INDEX-N where N is the OS major version
number.
IP_VERSION: integer
Restrict network access to specified IP version. 4 will
only allow IPv4 and 6 will only allow IPv6. Any other value
will use the system default. Repositories or command line
options can override this setting. Default: 0.
LOCK_RETRIES: integer
Number of attempts to obtain a lock before giving up and
exiting. Default: 5.
LOCK_WAIT: integer
Wait time in seconds to regain a lock if it is not
available. Default: 1.
METALOG: string
If set, pkg(8) will write a METALOG of the extracted files.
NAMESERVER: string
Hostname or IPv4 or IPv6 address of name server to use for
DNS resolution, overriding the system defaults in
/etc/resolv.conf. When given as a hostname, will be
converted to a list of IPv4 or IPv6 addresses by the default
mechanisms configured on the system. See getaddrinfo(3).
OSVERSION: integer
Specify the exact FreeBSD version for the target ABI. This
should be set in combination with the ABI option. The
format is the same as the format of __FreeBSD_version in
/usr/include/sys/param.h. Default: derived based on
ABI_FILE.
PERMISSIVE: boolean
Ignore conflicts while registering a package. Note that the
conflicting files will not be recorded as owned by the new
package. Default: NO.
PKG_CACHEDIR: string
Specifies the cache directory for packages. Default:
/var/cache/pkg.
PKG_CREATE_VERBOSE: boolean
When set to a true value, make pkg-create(8) use verbose
mode as standard. Default: NO.
PKG_DBDIR: string
Specifies the directory to use for storing the package
database files. Default: /var/db/pkg.
PKG_ENABLE_PLUGINS: boolean
When set to "YES", activate plugin support. Default: YES.
PKG_ENV: Key/Value list
This tells pkg(8) to set key/values to be passed in the
environment. This allow setting variables to configure the
http(s) fetcher. Which accepts environment variables
compatible with fetch(3), e.g., HTTP_PROXY. Default: not
set.
PKG_PLUGINS_DIR: string
Directory which pkg(8) will load plugins from. Default:
/usr/local/lib/pkg.
PKG_TRIGGERS_ENABLE: boolean
Enable or disable execution of triggers at the end of the
transactions. Default: YES.
PKG_TRIGGERS_DIR: array
List of directories where triggers are stored. Default:
/usr/share/pkg/triggers, /usr/local/share/pkg/triggers.
PKG_SSH_ARGS: string
Extra arguments to pass to ssh(1). This is a global
setting; it can be overridden on a per-repository basis
using the SSH_ARGS option in the repository configuration.
Default: not set.
PLIST_KEYWORDS_DIR: string
Directory containing definitions of plist keywords.
Default: PORTSDIR/keyword.
PLUGINS: array
List of plugins that pkg(8) should load. Default: not set.
PLUGINS_CONF_DIR: string
Directory containing per-plugin configuration files.
Default: /usr/local/etc/pkg.
PORTSDIR: string
Specifies the location to the Ports directory. Default:
/usr/ports.
READ_LOCK: boolean
Use read locking for query database. Default: NO.
REPOS_DIR: array
List of directories to search for repository configuration
files. Default: /etc/pkg/, /usr/local/etc/pkg/repos/.
REPO_AUTOUPDATE: boolean
When true, automatically check for and download updates to
/var/db/pkg/repo.sqlite when running one of: pkg fetch, pkg
install, pkg rquery, pkg search, pkg upgrade, or pkg version
-R. Default: YES.
RUN_SCRIPTS: boolean
Run pre-/post-installation action scripts. Default: YES.
SAT_SOLVER: string
Experimental: tells pkg to use an external SAT solver.
Default: not set.
SQLITE_PROFILE: boolean
Profile SQLite queries. Default: NO.
SSH_RESTRICT_DIR: string
Directory which the ssh subsystem will be restricted to.
Default: not set.
SYSLOG: boolean
Log all of the installation/deinstallation/upgrade
operations via syslog(3). Default: YES.
UNSET_TIMESTAMP: boolean
Do not include timestamps in the package tar(1) archive.
Normally, timestamps are copied from the staging directory
the package is created from. Default: NO.
VERSION_SOURCE: string
Default database for comparing version numbers in
pkg-version(8). Valid values are I for index, P for ports,
R for remote. Default: If unset, the algorithm described in
pkg-version(8) is used to determine the version source
automatically.
VALID_URL_SCHEME: array
List of url schemes that pkg can accept while parsing the
repository configuration file. Default: pkg+http,
pkg+https, https, http, file, ssh, tcp.
VULNXML_SITE: string
Specifies the URL to fetch the vuln.xml vulnerability
database from. Default:
https://vuxml.freebsd.org/freebsd/vuln.xml.xz.
WARN_SIZE_LIMIT: integer
When download and total change is less than than this
option, don't ask the user to confirm the desired action.
Default: 1048576 (1MB).
WORKERS_COUNT: integer
How many workers are used for pkg-repo. If set to 0,
hw.ncpu is used. Default: 0.
PKG_REINSTALL_ON_OPTIONS_CHANGE: boolean
Reinstall packages if options changed between the local
version and the remote version. Default: YES.
AUTOMERGE: boolean
When enabled, automatically attempt to merge configuration
files during package upgrades. Default: YES.
MERGETOOL: string
Specifies an external tool command to use for merging
configuration files during package upgrades. Used in
conjunction with AUTOMERGE. Default: not set.
FORCE_CAN_REMOVE_VITAL: boolean
When true, the -f (force) flag is allowed to override the
protection on vital packages, allowing them to be removed.
Default: YES.
DEBUG_SCHEDULER_DOT_FILE: string
When defined to a valid path, pkg will generate a dot(1)
file with the dependency graph of the internal scheduler.
Similar to DOT_FILE but specifically for the job scheduler.
Default: not set.
REPOSITORIES: object
Allows defining repositories directly within pkg.conf rather
than in separate repository configuration files. Default:
not set.
AUDIT_IGNORE_GLOB: array
A list of glob patterns for package names to ignore during
pkg-audit(8). Packages matching any of these patterns will
be excluded from vulnerability checks. Default: not set.
AUDIT_IGNORE_REGEX: array
A list of regular expressions for package names to ignore
during pkg-audit(8). Packages matching any of these
patterns will be excluded from vulnerability checks.
Default: not set.
REPO_ACCEPT_LEGACY_PKG: boolean
When true, allows pkg to accept packages in the legacy
package format from repositories. Default: NO.
FILES_IGNORE_GLOB: array
A list of glob patterns for files to ignore during package
installation and registration. Files matching these
patterns will be skipped. Default: not set.
FILES_IGNORE_REGEX: array
A list of regular expressions for files to ignore during
package installation and registration. Files matching these
patterns will be skipped. Default: not set.
SHLIB_PROVIDE_PATHS_NATIVE: array
List of absolute paths where native shared libraries are
provided. Used to filter which shared libraries a package
provides based on path. Default: not set.
SHLIB_PROVIDE_PATHS_COMPAT_32: array
List of absolute paths where 32-bit compatibility shared
libraries are provided. Default: not set.
SHLIB_PROVIDE_PATHS_COMPAT_LINUX: array
List of absolute paths where Linux compatibility shared
libraries are provided. Default: not set.
SHLIB_PROVIDE_PATHS_COMPAT_LINUX_32: array
List of absolute paths where 32-bit Linux compatibility
shared libraries are provided. Default: not set.
SHLIB_PROVIDE_IGNORE_GLOB: array
List of glob patterns to ignore when computing shared
libraries provided by a package. Default: not set.
SHLIB_PROVIDE_IGNORE_REGEX: array
List of regular expressions to ignore when computing shared
libraries provided by a package. Default: not set.
SHLIB_REQUIRE_IGNORE_GLOB: array
List of glob patterns to ignore when computing shared
libraries required by a package. Default: not set.
SHLIB_REQUIRE_IGNORE_REGEX: array
List of regular expressions to ignore when computing shared
libraries required by a package. Default: not set.
PKG_DEBUG_FLAGS: array
Controls which debug subsystems produce output. Default:
all.
TRACK_LINUX_COMPAT_SHLIBS: boolean
When enabled, pkg tracks Linux compatibility shared
libraries. Default: NO.
PKG_RWHICH_DATABASE: boolean
Controls whether pkg-update(8) fetches the remote file
listing database and pkg-rwhich(8) usrs it. When set to NO,
pkg-update(8) will not download the compressed file listing
from repositories and pkg-rwhich(8) will return no results.
A per-repository override rwhich_database can also be set in
the repository configuration. The global option takes
precedence: if set to NO, it disables rwhich for all
repositories regardless of per-repository settings.
Default: YES.
REPOSITORY CONFIGURATION
To use a repository you will need at least one repository configuration
file.
Repository configuration files are searched for in order of the
directories listed in the REPOS_DIR array, which defaults to /etc/pkg/
and /usr/local/etc/pkg/repos/.
Filenames are arbitrary, but should end in `.conf'. For example
/usr/local/etc/pkg/repos/myrepo.conf.
A repository file is in UCL format and has the following form:
myrepo:
ENV: object A list of key value entries that will be
passed as environment variable for the
bundled fetch(3), per repository.
URL: string URL for this repository only.
ENABLED: boolean The repository will be used only if this
option is enabled. Default: YES.
MIRROR_TYPE: string MIRROR_TYPE for this repository only.
Default: NONE. Any of HTTP or SRV or NONE.
SIGNATURE_TYPE: string
Specifies what type of signature this
repository uses. Can be one of NONE,
PUBKEY or FINGERPRINTS. (default: NONE)
PUBKEY: string This should be set to a path containing
public key for this repository only.
(default: NONE)
FINGERPRINTS: string
This should be set to a path containing
known signatures for the repository.
IP_VERSION: integer Restrict network access to specified IP
version. 4 will only allow IPv4 and 6 will
only allow IPv6. Any other value will use
the system default. This option overrides
the global setting with the same name and
can be overwritten by a command line
option. Default: 0.
PRIORITY: integer Set the priority of the repository. Higher
values are preferred. Default: 0.
SSH_ARGS: string Extra arguments to pass to ssh(1) when
fetching from this repository. This
overrides the global PKG_SSH_ARGS setting
for this repository only. Useful for
specifying a private key or connection
options on a per-repository basis.
Default: not set.
RWHICH_DATABASE: boolean
Controls whether pkg-rwhich(8) downloads
and uses the file listing database for this
specific repository. When disabled, the
file listing is not downloaded during
pkg-update(8) and pkg-rwhich(8) will not
search this repository. This option is
ignored if the global PKG_RWHICH_DATABASE
is set to NO. Default: YES.
For a MIRROR_TYPE of NONE, any of the following URL schemes: http://,
https://, file://, ssh://, tcp://. Where MIRROR_TYPE is SRV, you should
use a pkg+http:// or pkg+https:// (etc.) URL scheme. Using an http://
URL implies that the hostname part is a simple hostname according to RFC
2616, and is no longer accepted.
When SIGNATURE_TYPE is NONE, then no signature checking will be done on
the repository. When SIGNATURE_TYPE is PUBKEY, then the PUBKEY option
will be used for signature verification. This option is for use with the
built-in signing support. When SIGNATURE_TYPE is FINGERPRINTS, then the
FINGERPRINTS option will be used for signature verification. This option
is for use with an external signing command. See pkg-repo(8) for more
discussion on signature types.
If FINGERPRINTS is set to /usr/local/etc/pkg/fingerprints/myrepo, then
the directories /usr/local/etc/pkg/fingerprints/myrepo/trusted and
/usr/local/etc/pkg/fingerprints/myrepo/revoked should exist with known
good and bad fingerprints, respectively. Files in those directories
should be in the format:
function: sha256
fingerprint: sha256_representation_of_the_public_key
The repository tag myrepo is an arbitrary string. Reusing the repository
tag will cause those items defined in configuration files later on the
REPOS_DIR search path to overwrite the equivalent settings for the same
tag earlier on the search path. Hence the very common idiom, used to
turn off the default FreeBSD configuration shipped in
/etc/pkg/FreeBSD.conf. Rather than editing that file directly, create
/usr/local/etc/pkg/repos/FreeBSD.conf with this content:
FreeBSD: { enabled: NO }
Repositories are processed in the order they are found on the REPOS_DIR
search path, with individual repository configuration files in the same
directory processed in alphabetical order. Settings from files later in
the search path will override those from earlier ones. Packages are
selected preferentially out of all the repositories that contain them
from the repository with the highest priority, so long as they are
suitable to solve the necessary dependency requirements. However, this
preference may be overruled when CONSERVATIVE_UPGRADE is set to true, in
which case a package will as far as possible always be upgraded from the
same repository the older installed version came from, as given in the
repository annotation of the installed package. See pkg-repository(5)
for details.
It is possible to specify more than one repository per file.
VARIABLES
The following variables will be expanded during the parsing of pkg.conf.
ABI Expands to the ABI string (e.g. `FreeBSD:14:amd64').
OSNAME Expands to the name of the target operating system.
RELEASE
Expands to the full version of the target operating system.
VERSION_MAJOR
Expands to the major version of the target operating system. Can
be overridden via -o VERSION_MAJOR=value or by setting the
VERSION_MAJOR environment variable.
VERSION_MINOR
Expands to the minor version of the target operating system. Can
be overridden via -o VERSION_MINOR=value or by setting the
VERSION_MINOR environment variable.
OSVERSION
If targeting FreeBSD, expands to the target version in the same
format as __FreeBSD_version in /usr/include/sys/param.h.
ARCH Expands to the architecture of the system.
Since the values of these variables are affected by some options that may
be set in pkg.conf (for example ABI or ABI_FILE), it is necessary to
parse pkg.conf in two passes. The first pass only parses the ABI,
ABI_FILE, and OSVERSION options and does no variable expansion. The
second pass expands the variables listed above and ignores the ABI,
ABI_FILE, and OSVERSION options.
ENVIRONMENT
An environment variable with the same name as the option in the
configuration file always overrides the value of an option set in the
file.
EXAMPLES
FreeBSD latest ports repository configuration:
FreeBSD-ports: {
url: "pkg+https://pkg.freebsd.org/${ABI}/latest",
enabled: true,
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
mirror_type: "srv"
}
FreeBSD latest base repository configuration:
FreeBSD-base: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/base_latest",
enabled: true,
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
mirror_type: "srv"
}
FreeBSD quarterly kernel modules repository configuration:
FreeBSD-ports-kmods: {
url: "pkg+https://pkg.freebsd.org/${ABI}/kmods_quarterly_${VERSION_MINOR}",
enabled: true,
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkg",
mirror_type: "srv"
}
Example for pkg.conf:
pkg_dbdir: "/var/db/pkg"
pkg_cachedir: "/var/cache/pkg"
portsdir: "/usr/ports"
handle_rc_scripts: false
assume_always_yes: false
repos_dir: [
"/etc/pkg",
"/usr/local/etc/pkg/repos",
]
syslog: true
developer_mode: false
pkg_env: {
http_proxy: "http://myproxy:3128",
}
alias: {
origin: "info -qo",
nonauto: "query -e '%a == 0' '%n-%v'"
}
To bootstrap pkg(8) using a private repository (Assuming a pkg(7) new
enough to support the bootstrap command.):
# cat > /usr/local/etc/pkg/repos/example.conf <<EOF
example: {
url: http://pkgrepo.example.com/${ABI}
}
EOF
# cat > /usr/local/etc/pkg/repos/FreeBSD.conf <<EOF
FreeBSD: {
enabled: NO
}
EOF
# env PACKAGESITE='http://pkgrepo.example.com/${ABI}' /usr/sbin/pkg bootstrap
Note that pkg(7) uses PACKAGESITE for the URL to download pkg(8) from,
and subsequently passes it in the environment to pkg-static(8), which
ignores it (possibly with a deprecation warning that should be ignored),
and reads the configuration files instead.
SEE ALSO
pkg_checksum(3), pkg_create(3), pkg_printf(3), pkg_repo_create(3),
pkg_repos(3), pkg-keywords(5), pkg-lua-script(5), pkg-repository(5),
pkg-script(5), pkg-triggers(5), pkg(8), pkg-add(8), pkg-alias(8),
pkg-annotate(8), pkg-audit(8), pkg-autoremove(8), pkg-check(8),
pkg-checksum(8), pkg-clean(8), pkg-config(8), pkg-create(8),
pkg-delete(8), pkg-fetch(8), pkg-help(8), pkg-info(8), pkg-install(8),
pkg-key(8), pkg-lock(8), pkg-plugins(8), pkg-query(8), pkg-register(8),
pkg-repo(8), pkg-repositories(8), pkg-rquery(8), pkg-rwhich(8),
pkg-search(8), pkg-set(8), pkg-shell(8), pkg-shlib(8), pkg-ssh(8),
pkg-stats(8), pkg-triggers(8), pkg-unregister(8), pkg-update(8),
pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8)
FreeBSD 15.1-STABLE-HBSD May 28, 2026 PKG.CONF(5)