PKG.CONF(5)

📦 version 2.7.5, in nixos 26.05, nixpkgs unstable

💖 NAME 💖

pkg.conf — the system-wide configuration file for pkg(8). This is the pkg.conf(5) manual page, bestie, and it's all about the file that tells the pkg(8) tools how to behave.

🌸 DESCRIPTION 🌸

okay so 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. (Yes, you can leave little notes for yourself, the parser will not read them.)

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 (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. Event messages should be formatted as JSON. Default: not set.
  • FETCH_RETRY (integer) — Number of times to retry a failed fetch of a file. 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 libcurl(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 the User-agent to be sent to the 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 allows 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 — where your Ports tree lives 🗂️. Default: /usr/ports.
  • READ_LOCK boolean — use read locking for the query database. Default: NO.
  • REPOS_DIR array — the list of directories pkg digs through looking for repo config files 🔍. Default: /etc/pkg/, /usr/local/etc/pkg/repos/.
  • REPO_AUTOUPDATE boolean — when true, pkg auto-checks for and downloads updates to /var/db/pkg/repo.sqlite whenever you run one of: pkg fetch, pkg install, pkg rquery, pkg search, pkg upgrade, or pkg version -R. Default: YES. like it just keeps itself fresh, no cap ✨
  • 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 — the directory the ssh subsystem gets restricted to. Default: not set.
  • SYSLOG boolean — log all the install/uninstall/upgrade operations via syslog(3). Default: YES.
  • UNSET_TIMESTAMP boolean — don't put timestamps in the package tar(1) archive. Normally timestamps get copied over from the staging directory the package was created from. Default: NO.
  • VERSION_SOURCE string — the default database for comparing version numbers in pkg-version(8). Valid values: I for index, P for ports, R for remote. Default: if it's unset, the algorithm described in pkg-version(8) figures out the version source for you automatically bestie does the thinking so you don't have to 🧠.
  • VALID_URL_SCHEME array — the list of url schemes pkg will accept while parsing the repository config file. Default: pkg+http, pkg+https, https, http, file, ssh, tcp.
  • VULNXML_SITE string — the URL to fetch the vuln.xml vulnerability database from. Default: https://vuxml.freebsd.org/freebsd/vuln.xml.xz.
  • WARN_SIZE_LIMIT integer — when the download and total change is less than this option, pkg won't ask you to confirm the action you want. Default: 1048576 (1MB).
  • WORKERS_COUNT integer — how many workers get used for pkg-repo. Set it to 0 and hw.ncpu gets used instead. Default: 0.
  • PKG_REINSTALL_ON_OPTIONS_CHANGE boolean — reinstall packages if the options changed between the local version and the remote version. Default: YES.
  • AUTOMERGE boolean — when it's on, pkg automatically tries to merge configuration files during package upgrades. Default: YES.
  • MERGETOOL string — an external tool command to use for merging configuration files during package upgrades. Pairs up 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, which means they can get removed. Default: YES. yes this is exactly as scary as it sounds, be careful 💀
  • DEBUG_SCHEDULER_DOT_FILE string — when it's set to a valid path, pkg generates a dot(1) file with the dependency graph of the internal scheduler. Kinda like DOT_FILE but specifically for the job scheduler. Default: not set.
  • REPOSITORIES object — lets you define repositories straight up inside pkg.conf instead of in separate repository config files. Default: not set.
  • AUDIT_IGNORE_GLOB array — a list of glob patterns for package names to ignore during pkg-audit(8). Anything matching any of these patterns gets 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). Anything matching any of these patterns gets excluded from vulnerability checks. Default: not set.
  • REPO_ACCEPT_LEGACY_PKG boolean — when true, pkg is allowed 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 get 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 get skipped. Default: not set.

okay we're entering the shlib era of the page, stay with me 🦋

  • SHLIB_PROVIDE_PATHS_NATIVE array — list of absolute paths where native shared libraries are provided. It's 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 the shared libraries a package provides. Default: not set.
  • SHLIB_PROVIDE_IGNORE_REGEX array — list of regular expressions to ignore when computing the shared libraries a package provides. Default: not set.
  • SHLIB_REQUIRE_IGNORE_GLOB array — list of glob patterns to ignore when computing the shared libraries a package requires. Default: not set.
  • SHLIB_REQUIRE_IGNORE_REGEX array — list of regular expressions to ignore when computing the shared libraries a package requires. Default: not set.
  • PKG_DEBUG_FLAGS array — controls which debug subsystems actually produce output. Default: all.
  • TRACK_LINUX_COMPAT_SHLIBS boolean — when it's enabled, pkg tracks Linux compatibility shared libraries. Default: NO.

🗂️ REPOSITORY CONFIGURATION

okay so bestie, here's the tea ☕ — if you want to actually use a repository, you need at least one repository configuration file. no file, no repo, no packages. that's the whole vibe check.

pkg goes looking for repository config files in the order of the directories listed in the REPOS_DIR array, which defaults to /etc/pkg/ and /usr/local/etc/pkg/repos/ 💅

Filenames are honestly arbitrary — call it whatever — but they should end in .conf. for example: /usr/local/etc/pkg/repos/myrepo.conf ✨

A repository file is in UCL format and has this form:

myrepo:

and inside it, these keys are available (this is giving very much "menu of options", and we love her for it):

  • ENV: object — a list of key value entries that get passed as environment variables to the bundled fetch(3), per repository. 🫶
  • URL: string — the URL, but like, for this repository only.
  • ENABLED: boolean — the repository is only used if this is enabled. Default: YES.
  • MIRROR_TYPE: string — the 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 — set this to a path containing the public key for this repository only. (default: NONE)
  • FINGERPRINTS: string — set this to a path containing known signatures for the repository.
  • IP_VERSION: integer — restricts network access to the specified IP version. 4 will only allow IPv4 and 6 will only allow IPv6. any other value will use the system default. heads up: this option overrides the global setting with the same name, and can itself be overwritten by a command line option. Default: 0.
  • PRIORITY: integer — sets 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. super useful for specifying a private key or connection options on a per-repository basis. Default: not set.

For a MIRROR_TYPE of NONE, any of the following URL schemes work: http://, https://, file://, ssh://, tcp://. but where MIRROR_TYPE is SRV, you should use a pkg+http:// or pkg+https:// (etc.) URL scheme. also, using an http:// URL implies that the hostname part is a simple hostname according to RFC 2616, and is no longer accepted 💀 so don't do that.

When SIGNATURE_TYPE is NONE, then no signature checking will be done on the repository 😭. When SIGNATURE_TYPE is PUBKEY, then the PUBKEY option is used for signature verification — this one's for the built-in signing support. When SIGNATURE_TYPE is FINGERPRINTS, then the FINGERPRINTS option is used for signature verification — this one's for use with an external signing command. see pkg-repo(8) if you want 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, containing known good and bad fingerprints respectively. files in those directories should be in this 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 (rude), create /usr/local/etc/pkg/repos/FreeBSD.conf with this content:

FreeBSD: { enabled: NO }

Repositories are processed in the order they're 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're 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 the details, iykyk.

and yes bestie, it is possible to specify more than one repository per file 💅 iconic.

🔮 VARIABLES

The following variables will be expanded during the parsing of pkg.conf. it's giving variable substitution, it's giving ✨ magic ✨.

  • ABI — expands to the ABI string (e.g. FreeBSD:14:amd64).
  • OSNAME — expands to the 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.
  • VERSION_MINOR — expands to the minor version of the target operating system.
  • 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. two-pass parse, main character energy fr fr.

🌿 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. periodt. 💜

🌸 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_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-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-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)

and that's the whole page, bestie!! 🎀 you ate that. this one came from the Debian crew, dated March 11, 2026, and it lives in the PKG.CONF(5) section of the manual — go forth and configure your repos like the icon you are 💖🦋✨

📦 where this page comes from