PKG-REPOSITORY(5) FreeBSD File Formats Manual PKG-REPOSITORY(5)
NAME
package repository - format and operation of package repositories used by
pkg(8).
DESCRIPTION
Package repositories used by the pkg(8) program consist of one or more
collections of packages together with package catalogues and various
other collected package metadata.
Each collection consists of packages suitable for installation on a
specific system ABI: a combination of operating system, CPU architecture,
OS version, word size and, for certain processors, endianness or similar
attributes.
The package collections are typically made available to users for
download via a web server although various other means of access may be
employed. Encoding the ABI value into the repository URL allows pkg to
automatically select the correct package collection by expanding the
special token ${ABI} in pkg.conf.
Repositories may be mirrored over several sites: pkg has built-in support
for discovering available mirrors dynamically given a common URL by
several mechanisms.
REPOSITORY FORMAT
The current repository format is version 2. It is generated by
pkg-repo(8).
A repository consists of package files (.pkg) and a set of catalogue
files at the root of the repository.
Catalogue Files
The following files are generated at the REPOSITORY_ROOT by pkg-repo(8):
meta.conf A UCL file describing the repository metadata. It
contains the following fields:
version The repository format version (currently
2).
packing_format The compression format used for
catalogue archives (tzst, txz, tbz, tgz,
or tar).
manifests The name of the uncompressed manifests
file (default: packagesite.yaml).
manifests_archive
The base name of the compressed
manifests archive (default:
packagesite).
data The name of the uncompressed data file
(default: data).
data_archive The base name of the compressed data
archive (default: data).
filesite The name of the uncompressed file
listing (default: files).
filesite_archive
The base name of the compressed file
listing archive (default: files).
maintainer Optional maintainer string.
source Optional source string.
source_identifier
Optional source identifier.
revision Optional integer revision number.
eol Optional end-of-life timestamp (Unix
epoch).
packagesite.pkg (Deprecated, kept for backward compatibility.) A
compressed archive containing packagesite.yaml, a
concatenation of the manifests from all packages in the
repository. Each manifest is represented as a single-
line compact JSON text, and the manifests are separated
by newlines. Superseded by data.pkg.
data.pkg The primary catalogue archive, containing the data file
in JSON format with the following top-level keys:
groups An array of package group definitions
(if configured).
expired_packages An array of expired package entries
(if configured).
packages An array of all package manifests.
files.pkg (Optional, generated with -l flag to pkg-repo(8)). A
compressed archive containing files, a directory-grouped
listing of all files in all packages in the repository.
The file uses a line-based text format. Since newlines
cannot appear in Unix file paths, each line is
unambiguous and no encoding is required; bytes pass
through as-is.
The file is divided into two sections separated by an
empty line:
1. A front-compressed directory dictionary, using the
same technique as locate(1). Directories are
sorted lexicographically; each line is "N suffix"
where N is the number of bytes to keep from the
previous entry and suffix is appended to form the
full path. The line number (starting at 0) is the
directory's index. Because sorted paths share long
common prefixes, most of each path is elided.
2. Package blocks, each separated by an empty line.
Within each block:
o The first line is the package header: "name
version".
o A line starting with `>' is a directory index,
selecting the current directory from the
dictionary (e.g. `>2' selects directory index
2). The `>' prefix prevents ambiguity with
file basenames that happen to be purely
numeric.
o All other non-empty lines are file basenames
within the current directory.
Example:
0 /usr/local/bin
15 lib
15 share/man/man1
bash 5.2.26
>0
bash
bashbug
>2
bash.1.gz
curl 8.7.1
>0
curl
>1
libcurl.so.4
In this example, the first directory is /usr/local/bin
(index 0, prefix length 0 = full path). Index 1 keeps
15 bytes ("/usr/local/") and appends "lib" to form
/usr/local/lib. Index 2 likewise keeps the same 15-byte
prefix and appends "share/man/man1". The common prefix
is never repeated, significantly reducing the size of
the directory dictionary. When a client runs
pkg-update(8), the data is fetched and loaded into the
local repository database (tables file_dirs and
pkg_files), enabling pkg-rwhich(8) queries.
Compressed archives use the .pkg extension and default to Zstandard
(tzst) compression. When a repository uses a different compression
format, the meta.conf file indicates which format is used.
Repositories may optionally be signed. See pkg-repo(8) for details on
signing repositories.
Package Layout
Packages are stored as .pkg files within the repository hierarchy. The
repository catalogue records the relative path from the REPOSITORY_ROOT
to each package, allowing the full URL for downloading to be constructed.
Each of the packages listed in the repository catalogue must have a
unique name. There are no other constraints: package sets are not
required to be either complete (i.e., with all dependencies satisfied) or
self-consistent within a single repository.
Hash Mode
When pkg-repo(8) is invoked with the -h flag, packages are reorganized
into a Hashed subdirectory with a SHA256 hash appended to the filename,
separated by a tilde (`~'). With the additional -s flag, symbolic links
are created in the original location pointing to the hashed file.
Groups
Package groups allow organizing packages into logical collections.
Groups are defined in UCL files within a directory passed to pkg-repo(8)
via the -g flag. Each group file contains:
name The group name (required).
comment A description of the group (required).
requires An array of required group names.
depends An array of dependent group names.
Expired Packages
Repositories can declare packages as expired. Expired packages are
defined in UCL files and contain:
name The package name (required).
reason Why the package was expired.
replaced_by The replacement package, if any.
REPOSITORY ACCESS METHODS
pkg uses fetch(3) for HTTP and HTTPS access, and has built-in support for
SSH and local file:// access.
The following URL schemes are supported: pkg+http://, pkg+https://,
https://, http://, file://, ssh:// and tcp://.
The pkg+http:// and pkg+https:// schemes are used with SRV mirror type to
enable DNS-based mirror discovery.
For ssh:// repositories, extra arguments can be passed to ssh(1) via the
SSH_ARGS per-repository option or the global PKG_SSH_ARGS setting in
pkg.conf(5). The per-repository setting takes precedence over the global
one. This is useful for specifying a private key (-i) or other
connection options for a specific repository.
Additional URL schemes can be configured via the VALID_URL_SCHEME option
in pkg.conf(5).
The following environment variables affect HTTP and HTTPS access:
HTTP_PROXY, http_proxy, HTTPS_PROXY, NO_PROXY and no_proxy. The
HTTP_USER_AGENT can be configured in pkg.conf(5).
REPOSITORY MIRRORING
Multiple copies of a repository can be provided for resilience or to
scale up site capacity. Two schemes are provided to auto-discover sets
of mirrors given a single repository URL.
HTTP The repository URL should download a text document containing a
sequence of lines beginning with `URL:' followed by any amount of
white space and one URL for a repository mirror. Any lines not
matching this pattern are ignored. Mirrors are tried in the order
listed until a download succeeds.
SRV For an SRV mirrored repository where the URL is specified as
pkg+http://pkgrepo.example.org/ SRV records should be set up in the
DNS:
$ORIGIN example.com
_http._tcp.pkgrepo IN SRV 10 1 80 mirror0
IN SRV 20 1 80 mirror1
where the SRV priority and weight parameters are used to control
search order and traffic weighting between sites, and the port
number and hostname are used to construct the individual mirror
URLs.
Mirrored repositories are assumed to have identical content, and only one
copy of the repository catalogue will be downloaded to apply to all
mirror sites.
WORKING WITH MULTIPLE REPOSITORIES
Where several different repositories are configured pkg will search
amongst them all in the order specified by the PRIORITY settings in the
repo.conf files, unless directed to use a single repository by the -r
flag to pkg-fetch(8), pkg-install(8), pkg-upgrade(8), pkg-search(8) or
pkg-rquery(8).
Where several different versions of the same package are available, pkg
will select the one with the highest version to install or to upgrade an
installed package to, even if a lower numbered version can be found in a
repository earlier in the list. This applies even if an explicit version
is stated on the command line. Thus if packages example-1.0.0 and
example-1.0.1 are available in configured repositories, then
pkg install example-1.0.0
will actually result in example-1.0.1 being installed. To override this
behaviour, on first installation of the package select the repository
with the appropriate version:
pkg install -r repo-a example-1.0.0
and then to make updates to that package "sticky" to the same repository,
set the value CONSERVATIVE_UPGRADE to true in pkg.conf.
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-script(5),
pkg-triggers(5), pkg.conf(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-REPOSITORY(5)