PKG-REPOSITORY(5)

📦 version 2.7.5, in nixos 26.05, nixpkgs unstable

💅 PKG-REPOSITORY(5) — like, the whole entire vibe of package repositories, bestie

okay so this is the File Formats Manual page for pkg-repository, and honestly? it's giving backstage tour of where your packages actually live. pull up a chair 🎀

✨ NAME ✨

package repository — the format and operation of package repositories used by pkg(8). yeah. that's the whole name. iconic brevity.

🌸 DESCRIPTION 🌸

So a package repository, as used by pkg(8), is literally just one or more collections of packages hanging out together with their package catalogues and a bunch of other collected package metadata. it's a whole friend group, not just one guy.

Each collection is made of packages that are suitable for installation on a specific system ABI — and an ABI is a combination of: operating system, CPU architecture, OS version, word size, and for certain processors, endianness or similar attributes. that's a lot of qualifiers but she's worth it 💅

These package collections are typically made available to users for download via a web server, although various other means of access may be employed. and here's the slay part: encoding the ABI value into the repository URL lets pkg automatically select the correct package collection by expanding the special token ${ABI} in pkg.conf. like it literally reads the room. queen behaviour 👑

Repositories may also be mirrored over several sites — pkg has built-in support for discovering available mirrors dynamically given a common URL by several mechanisms. we love a resourceful icon.

🦋 REPOSITORY FORMAT 🦋

The current repository format is version 2. no cap. it's 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. she 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: filesite.yaml).
    • filesite_archive — the base name of the compressed file listing archive (default: filesite).
    • 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, which is 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. she's retired but we still respect her 🙈
  • 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.
  • filesite.pkg — (optional, generated with -l flag to pkg-repo(8)). a compressed archive containing filesite.yaml, a concatenation of the file lists from all packages in the repository.

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. she always tells you what she's about 💖

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, which allows the full URL for downloading to be constructed. lowkey elegant.

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. she's chill like that.

🔥 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. it's giving ✨organized chaos✨

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

gone but not forgotten, fr fr 😭

⭐ REPOSITORY ACCESS METHODS ⭐

pkg uses libcurl(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://. collect them all bestie 💅

The pkg+http:// and pkg+https:// schemes are used with SRV mirror type to enable DNS-based mirror discovery. iykyk.

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. so specific. so her. 🗝️

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. survivors, fr.

  • 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. she's persistent and we love that 🫶
  • 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. DNS but make it fashion 💫

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. efficient queen. no notes.

👑 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. and this applies even if an explicit version is stated on the command line. that's not a bug, that's the whole personality.

So 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. yeah. she said what she said. 💀

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. loyalty!! we stan a committed relationship 💖

🎀 SEE ALSO 🎀

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

a whole reading list. go off. 📚✨

💖 and that's the page!! 💖 this baddie was written on the Debian build, dated December 12, 2025, and it's the PKG-REPOSITORY(5) manual page — read her, cite her, love her. periodt. 🎀🦋💅

📦 where this page comes from