.\"
.\" FreeBSD pkg - a next generation package for the installation and
.\" maintenance of non-core utilities.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\"
.\"     @(#)pkg-repository.5
.\" $FreeBSD$
.\"
.Dd December 12, 2025
.Dt PKG-REPOSITORY 5
.Os
.Sh NAME
.Nm "package repository"
.Nd format and operation of package repositories used by
.Xr pkg 8 .
.Sh DESCRIPTION
.Nm "Package repositories"
used by the
.Xr pkg 8
program consist of one or more collections of packages together with
package catalogues and various other collected package metadata.
.Pp
Each collection consists of packages suitable for installation on a
specific system
.Sy ABI :
a combination of operating system, CPU architecture, OS version, word
size and, for certain processors, endianness or similar attributes.
.Pp
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
.Sy ABI
value into the repository URL allows
.Nm pkg
to automatically select the correct package collection by expanding the
special token
.Cm ${ABI}
in
.Pa pkg.conf .
.Pp
Repositories may be mirrored over several sites:
.Nm pkg
has built-in support for discovering available mirrors dynamically
given a common URL by several mechanisms.
.Sh REPOSITORY FORMAT
The current repository format is version 2.
It is generated by
.Xr pkg-repo 8 .
.Pp
A repository consists of package files
.Pq Pa .pkg
and a set of catalogue files at the root of the repository.
.Ss Catalogue Files
The following files are generated at the
.Cm REPOSITORY_ROOT
by
.Xr pkg-repo 8 :
.Bl -tag -width "packagesite.pkg"
.It Pa meta.conf
A UCL file describing the repository metadata.
It contains the following fields:
.Bl -tag -width "packing_format" -compact
.It Cm version
The repository format version (currently 2).
.It Cm packing_format
The compression format used for catalogue archives
.Pq tzst, txz, tbz, tgz, or tar .
.It Cm manifests
The name of the uncompressed manifests file
.Pq default: Pa packagesite.yaml .
.It Cm manifests_archive
The base name of the compressed manifests archive
.Pq default: Pa packagesite .
.It Cm data
The name of the uncompressed data file
.Pq default: Pa data .
.It Cm data_archive
The base name of the compressed data archive
.Pq default: Pa data .
.It Cm filesite
The name of the uncompressed file listing
.Pq default: Pa files .
.It Cm filesite_archive
The base name of the compressed file listing archive
.Pq default: Pa files .
.It Cm maintainer
Optional maintainer string.
.It Cm source
Optional source string.
.It Cm source_identifier
Optional source identifier.
.It Cm revision
Optional integer revision number.
.It Cm eol
Optional end-of-life timestamp (Unix epoch).
.El
.It Pa packagesite.pkg
(Deprecated, kept for backward compatibility.)
A compressed archive containing
.Pa 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
.Pa data.pkg .
.It Pa data.pkg
The primary catalogue archive, containing the
.Pa data
file in JSON format with the following top-level keys:
.Bl -tag -width "expired_packages" -compact
.It Cm groups
An array of package group definitions (if configured).
.It Cm expired_packages
An array of expired package entries (if configured).
.It Cm packages
An array of all package manifests.
.El
.It Pa files.pkg
(Optional, generated with
.Fl l
flag to
.Xr pkg-repo 8 ) .
A compressed archive containing
.Pa files ,
a directory-grouped listing of all files in all packages in the repository.
.Pp
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.
.Pp
The file is divided into two sections separated by an empty line:
.Bl -enum -compact
.It
A
.Em front-compressed directory dictionary ,
using the same technique as
.Xr locate 1 .
Directories are sorted lexicographically; each line is
.Do Ar N Ar suffix Dc
where
.Ar N
is the number of bytes to keep from the previous entry and
.Ar 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.
.It
.Em Package blocks ,
each separated by an empty line.
Within each block:
.Bl -bullet -compact
.It
The first line is the package header:
.Do name version Dc .
.It
A line starting with
.Ql >
is a directory index, selecting the current directory from the
dictionary (e.g.\&
.Ql >2
selects directory index 2).
The
.Ql >
prefix prevents ambiguity with file basenames that happen to be
purely numeric.
.It
All other non-empty lines are file basenames within the current directory.
.El
.El
.Pp
Example:
.Bd -literal -offset indent
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
.Ed
.Pp
In this example, the first directory is
.Pa /usr/local/bin
(index 0, prefix length 0 = full path).
Index 1 keeps 15 bytes
.Pq Dq /usr/local/
and appends
.Dq lib
to form
.Pa /usr/local/lib .
Index 2 likewise keeps the same 15-byte prefix and appends
.Dq share/man/man1 .
The common prefix is never repeated, significantly reducing the size
of the directory dictionary.
When a client runs
.Xr pkg-update 8 ,
the data is fetched and loaded into the local repository database
.Pq tables Pa file_dirs No and Pa pkg_files ,
enabling
.Xr pkg-rwhich 8
queries.
.El
.Pp
Compressed archives use the
.Pa .pkg
extension and default to Zstandard
.Pq tzst
compression.
When a repository uses a different compression format, the
.Pa meta.conf
file indicates which format is used.
.Pp
Repositories may optionally be signed.
See
.Xr pkg-repo 8
for details on signing repositories.
.Ss Package Layout
Packages are stored as
.Pa .pkg
files within the repository hierarchy.
The repository catalogue records the relative path from the
.Cm REPOSITORY_ROOT
to each package, allowing the full URL for downloading to be
constructed.
.Pp
Each of the packages listed in the repository catalogue must have a
unique
.Cm 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.
.Ss Hash Mode
When
.Xr pkg-repo 8
is invoked with the
.Fl h
flag, packages are reorganized into a
.Pa Hashed
subdirectory with a SHA256 hash appended to the filename, separated
by a tilde
.Pq Sq ~ .
With the additional
.Fl s
flag, symbolic links are created in the original location pointing
to the hashed file.
.Ss Groups
Package groups allow organizing packages into logical collections.
Groups are defined in UCL files within a directory passed to
.Xr pkg-repo 8
via the
.Fl g
flag.
Each group file contains:
.Bl -tag -width "requires" -compact
.It Cm name
The group name (required).
.It Cm comment
A description of the group (required).
.It Cm requires
An array of required group names.
.It Cm depends
An array of dependent group names.
.El
.Ss Expired Packages
Repositories can declare packages as expired.
Expired packages are defined in UCL files and contain:
.Bl -tag -width "replaced_by" -compact
.It Cm name
The package name (required).
.It Cm reason
Why the package was expired.
.It Cm replaced_by
The replacement package, if any.
.El
.Sh REPOSITORY ACCESS METHODS
.Nm pkg
uses
.Xr libcurl 3
for HTTP and HTTPS access, and has built-in support for
.Cm SSH
and local
.Cm file://
access.
.Pp
The following URL schemes are supported:
.Cm pkg+http:// ,
.Cm pkg+https:// ,
.Cm https:// ,
.Cm http:// ,
.Cm file:// ,
.Cm ssh://
and
.Cm tcp:// .
.Pp
The
.Cm pkg+http://
and
.Cm pkg+https://
schemes are used with
.Cm SRV
mirror type to enable DNS-based mirror discovery.
.Pp
For
.Cm ssh://
repositories, extra arguments can be passed to
.Xr ssh 1
via the
.Cm SSH_ARGS
per-repository option or the global
.Cm PKG_SSH_ARGS
setting in
.Xr pkg.conf 5 .
The per-repository setting takes precedence over the global one.
This is useful for specifying a private key
.Pq Fl i
or other connection options for a specific repository.
.Pp
Additional URL schemes can be configured via the
.Cm VALID_URL_SCHEME
option in
.Xr pkg.conf 5 .
.Pp
The following environment variables affect HTTP and HTTPS access:
.Ev HTTP_PROXY ,
.Ev http_proxy ,
.Ev HTTPS_PROXY ,
.Ev NO_PROXY
and
.Ev no_proxy .
The
.Cm HTTP_USER_AGENT
can be configured in
.Xr pkg.conf 5 .
.Sh 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.
.Bl -tag -width "HTTP"
.It Cm HTTP
The repository URL should download a text document containing a
sequence of lines beginning with
.Sq 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.
.It Cm SRV
For an SRV mirrored repository where the URL is specified as
.Pa pkg+http://pkgrepo.example.org/
.Cm SRV
records should be set up in the DNS:
.Bd -literal -offset indent
$ORIGIN example.com
_http._tcp.pkgrepo IN SRV 10 1 80 mirror0
                   IN SRV 20 1 80 mirror1
.Ed
.Pp
where the
.Cm 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.
.El
.Pp
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.
.Sh WORKING WITH MULTIPLE REPOSITORIES
Where several different repositories are configured
.Nm pkg
will search amongst them all in the order specified by the
.Cm PRIORITY
settings in the
.Pa repo.conf
files, unless directed to use a single repository by the
.Fl r
flag to
.Xr pkg-fetch 8 ,
.Xr pkg-install 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-search 8
or
.Xr pkg-rquery 8 .
.Pp
Where several different versions of the same package are available,
.Nm 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
.Pa example-1.0.0
and
.Pa example-1.0.1
are available in configured repositories, then
.Bd -literal -offset indent
pkg install example-1.0.0
.Ed
.Pp
will actually result in
.Pa example-1.0.1
being installed.
To override this behaviour, on first installation of the package
select the repository with the appropriate version:
.Bd -literal -offset indent
pkg install -r repo-a example-1.0.0
.Ed
.Pp
and then to make updates to that package
.Dq sticky
to the same repository, set the value
.Cm CONSERVATIVE_UPGRADE
to
.Sy true
in
.Pa pkg.conf .
.Sh SEE ALSO
.Xr pkg_checksum 3 ,
.Xr pkg_create 3 ,
.Xr pkg_printf 3 ,
.Xr pkg_repo_create 3 ,
.Xr pkg_repos 3 ,
.Xr pkg-keywords 5 ,
.Xr pkg-lua-script 5 ,
.Xr pkg-script 5 ,
.Xr pkg-triggers 5 ,
.Xr pkg.conf 5 ,
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-alias 8 ,
.Xr pkg-annotate 8 ,
.Xr pkg-audit 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-check 8 ,
.Xr pkg-checksum 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-config 8 ,
.Xr pkg-create 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-help 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-key 8 ,
.Xr pkg-lock 8 ,
.Xr pkg-plugins 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-repositories 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-rwhich 8 ,
.Xr pkg-search 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-ssh 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-triggers 8 ,
.Xr pkg-unregister 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8