FreeBSD Manual Pages
PKG.CONF(5) 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 se- quence 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). De- fault: 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 opera- tion. 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 (typi- cally 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 li- brary will be created. This package is named after the origi- nal 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. De- fault: 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. De- fault: not set. CASE_SENSITIVE_MATCH: boolean Match package names or regular expressions given on the com- mand 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 ver- bose debugging output. A setting of 0 disables debugging out- put. 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. 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 sup- ported 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 dein- stallation. 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_OSVERSION: boolean [FreeBSD specific] Ignore FreeBSD OS version check, useful on -STABLE and -CUR- RENT 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 exit- ing. 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 data- base 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 envi- ronment. This allow setting variables to configure the http(s) fetcher. Which accepts environment variables compati- ble 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. De- fault: not set. SQLITE_PROFILE: boolean Profile SQLite queries. Default: NO. SSH_RESTRICT_DIR: string Directory which the ssh subsystem will be restricted to. De- fault: 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. Nor- mally, 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-ver- sion(8). Valid values are I for index, P for ports, R for re- mote. Default: If unset, the algorithm described in pkg-ver- sion(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 ver- sion 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 configu- ration 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 pro- tection on vital packages, allowing them to be removed. De- fault: 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 dur- ing 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 in- stallation 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 pack- age installation and registration. Files matching these pat- terns will be skipped. Default: not set. SHLIB_PROVIDE_PATHS_NATIVE: array List of absolute paths where native shared libraries are pro- vided. Used to filter which shared libraries a package pro- vides based on path. Default: not set. SHLIB_PROVIDE_PATHS_COMPAT_32: array List of absolute paths where 32-bit compatibility shared li- braries are provided. Default: not set. SHLIB_PROVIDE_PATHS_COMPAT_LINUX: array List of absolute paths where Linux compatibility shared li- braries 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 li- braries 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 li- braries 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. 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 bun- dled fetch(3), per repository. URL: string URL for this repository only. ENABLED: boolean The repository will be used only if this op- tion is enabled. Default: YES. MIRROR_TYPE: string MIRROR_TYPE for this repository only. De- fault: NONE. Any of HTTP or SRV or NONE. SIGNATURE_TYPE: string Specifies what type of signature this reposi- tory uses. Can be one of NONE, PUBKEY or FINGERPRINTS. (default: NONE) PUBKEY: string This should be set to a path containing pub- lic 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 ver- sion. 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. De- fault: 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 fetch- ing from this repository. This overrides the global PKG_SSH_ARGS setting for this reposi- tory only. 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: 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 dis- cussion 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 di- rectory 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 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 op- tions. ENVIRONMENT An environment variable with the same name as the option in the configura- tion 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_create(3), pkg_printf(3), pkg_repo_create(3), pkg_repos(3), pkg-key- words(5), pkg-lua-script(5), pkg-repository(5), pkg-script(5), pkg-trig- gers(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-cre- ate(8), pkg-delete(8), pkg-fetch(8), pkg-help(8), pkg-info(8), pkg-in- stall(8), pkg-key(8), pkg-lock(8), pkg-plugins(8), pkg-query(8), pkg-regis- ter(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-trig- gers(8), pkg-unregister(8), pkg-update(8), pkg-updating(8), pkg-upgrade(8), pkg-version(8), pkg-which(8) FreeBSD ports 15.1 March 11, 2026 PKG.CONF(5)
NAME | DESCRIPTION | OPTIONS | REPOSITORY CONFIGURATION | VARIABLES | ENVIRONMENT | EXAMPLES | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=pkg.conf&manpath=FreeBSD+15.1-RELEASE+and+Ports>