ALPM-REPO-DESCV1(5)
💅 alpm-repo-desc(5) — the file format manual, bestie edition ✨
okay so real quick: this is a File Formats Manual page, section (5), for alpm-repo-desc. Buckle up, she's thorough 💖
🌸 NAME
alpm-repo-desc — the file format for the metadata representation of ALPM based packages in package repositories (version 1). periodt.
✨ DESCRIPTION
The alpm-repo-desc format is a textual format, and it represents the metadata of, like, one single package at a specific version in a repository. Each file describes a bunch of properties of an alpm-package file — its name, version, dependencies, size, licensing info, and more 🫶 (for the full list of properties, check its sections, they're all listed below).
The accumulation of all alpm-repo-desc files in an alpm-repo-db describes the current state of the repository (i.e. which packages are available, and in what version). the way that works is so satisfying ngl.
An operating system that relies on Arch Linux Package Management maintains one or more alpm-repo-db files, and each of those contains one alpm-repo-desc file per package. Each one is named desc and lives in a unique, per-package directory 👑 More specifically: package management software like pacman and related tools use this file format, e.g. to resolve dependencies and to display package information of alpm-package files in repositories.
The data in an alpm-repo-desc file is derived from an alpm-package. A lot of its metadata originates from the package's PKGINFO data. An alpm-repo-desc file is usually created by software that manages an alpm-repo, such as repo-add.
🚨 do NOT confuse the file format described in this document with thealpm-db-descfile format!! That one is used in the context of alibalpmdatabase and carries a different set of metadata — but it's usually also nameddesc. same name, different girl, iykyk 🙈
The alpm-repo-desc format exists in multiple versions. This document describes version 1, which is a legacy version and has been available since the release of pacman 5.1.0 on 2018-05-28 ⭐ For the latest specification, refer to alpm-repo-desc.
🎀 General Format
An alpm-repo-desc file is a UTF-8 encoded, newline-delimited file consisting of a series of sections.
Each section starts with a unique section header line. That section header line is followed by one or more lines, each with a section-specific value. All section-specific values must consist of printable ASCII characters[1] unless stated otherwise. A section ends when another section header line is encountered, or when the end of the file is reached 💀
Empty lines between sections are ignored. literally just vibes, they don't count.
🦋 Sections
Each section header line contains the section name in ALL CAPITAL LETTERS, surrounded by percent signs (e.g. %NAME%). Section names serve as the key for each section-specific value 🔑
Each section allows for a single section-specific value, following the section header line. As an exemption to this rule, the %LICENSE%, %GROUPS%, %CHECKDEPENDS%, %DEPENDS%, %OPTDEPENDS%, %REPLACES%, %CONFLICTS% and %PROVIDES% sections may have more than one section-specific value. those ones ate and left no crumbs 💅
💖 %FILENAME%
The file name of the alpm-package (e.g. example-1.2.3-any.pkg.tar.zst).
💖 %NAME%
An alpm-package-name, which represents the name of a package (e.g. example).
💖 %BASE%
An alpm-package-base, which represents the package base from which a package originates. If a package is not an alpm-split-package, the value is the same as that of the %NAME% section. If a package is an alpm-split-package, the value may be different from the one in the %NAME% section 👀
💖 %VERSION%
An alpm-package-version (full or full with epoch), which represents the version of a package (e.g. 1.0-1).
💖 %DESC%
The description of the package. The value is a UTF-8 string, zero or more characters long (e.g. A project used for something). If the description is empty, the section can be omitted 🌸
💖 %GROUPS%
An alpm-package-group that denotes a distribution-wide group the package is in. One or more values may be present. If the package is not in a group, the section is omitted.
The value is represented by a UTF-8 string. Although it is possible to use a UTF-8 string, it's highly recommended to rely on the alpm-package-name format for the value instead, because package managers may use a package group to install an entire group of packages. trust me on this one 🫶
💖 %CSIZE%
The size of the compressed alpm-package, in bytes. The value is a non-negative integer (e.g. 1818463).
💖 %ISIZE%
The size of the (uncompressed and unpacked) package contents, in bytes. The value is a non-negative integer representing the absolute size of the contents of the package, with multiple hardlinked files counted only once (e.g. 181849963). yes, only once, we're not out here double-counting 💀
💖 %MD5SUM%
The MD-5[2] hash digest of the alpm-package file. The string consists of 32 hexadecimal characters (e.g. d3b07384d113edec49eaa6238ad5ff00).
💖 %SHA256SUM%
The SHA-256[3] hash digest of the alpm-package file. The string consists of 64 hexadecimal characters (e.g. b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c).
💖 %PGPSIG%
The base64[4] encoded OpenPGP signature[5] for the alpm-package file (e.g. iHUEABYKAB0WIQRizHP4hOUpV7L92IObeih9mi7GCAUCaBZuVAAKCRCbeih9mi7GCIlMAP9ws/jU4f580ZRQlTQKvUiLbAZOdcB7mQQj83hD1Nc/GwD/WIHhO1/OQkpMERejUrLo3AgVmY3b4/uGhx9XufWEbgE=). iconic string honestly 🔥
💖 %URL%
The URL for the project of the package. The value is a valid URL or an empty string (e.g. https://example.org). If the URL is an empty string, the section can be omitted.
💖 %LICENSE%
An optional set of license identifiers that apply for the package. One or more values may be present. If there is no license identifier, the section is omitted.
Each value represents a license identifier, which is a string of non-zero length (e.g. GPL). Although no specific restrictions are enforced for the value aside from its length, it's highly recommended to rely on SPDX license expressions (e.g. GPL-3.0-or-later or Apache-2.0 OR MIT). See SPDX License List[6] for further information. slay in a legally-compliant way ⚖️✨
💖 %ARCH%
The architecture of the package (see alpm-architecture for further information). The value must be covered by the set of alphanumeric characters and _ (e.g. x86_64 or any).
💖 %BUILDDATE%
The date at which the build of the package started. The value must be numeric and represent the seconds since the Epoch, aka. "Unix time" (e.g. 1729181726).
💖 %PACKAGER%
The User ID of the entity that built the package. The value is meant to be used for identity lookups and represents an OpenPGP User ID[7]. As such, the value is a UTF-8-encoded string that is conventionally composed of a name and an e-mail address, which aligns with the format described in RFC 28228. 🎀
💖 %REPLACES%
Another virtual component or package that the package replaces upon installation. One or more values may be present. If the package does not replace anything, the section is omitted. The value is an alpm-package-relation of type replacement (e.g. example or example=1.0.0).
💖 %CONFLICTS%
Another virtual component or package that the package conflicts with. One or more values may be present. If the package does not conflict with anything, the section is omitted. The value is an alpm-package-relation of type conflict (e.g. example or example=1.0.0). drama, but make it package management 💀
💖 %PROVIDES%
Another virtual component or package that the package provides. One or more values may be present. If the package does not provide anything, the section is omitted. The value is an alpm-package-relation of type provision (e.g. example or example=1.0.0).
💖 %DEPENDS%
A run-time dependency of the package (virtual component or package). One or more values may be present. If the package has no run-time dependency, the section is omitted. The value is an alpm-package-relation of type run-time dependency (e.g. example or example=1.0.0).
💖 %OPTDEPENDS%
An optional dependency of the package (virtual component or package). One or more values may be present. If the package has no optional dependency, the section is omitted. The value is an alpm-package-relation of type optional dependency (e.g. example or example: this is a description).
💖 %MAKEDEPENDS%
A dependency for building the upstream software of the package. One or more values may be present. If the package has no build dependency, the section is omitted. The value is an alpm-package-relation of type build dependency (e.g. example or example=1.0.0).
💖 %CHECKDEPENDS%
A dependency for running tests of the package's upstream project. One or more values may be present. If the package has no test dependency, the section is omitted. The value is an alpm-package-relation of type test dependency (e.g. example or example=1.0.0).
🌈 EXAMPLES
A full example of an alpm-repo-desc file for a package named example in version 1.0.0-1:
%FILENAME%
example-1.0.0-1-any.pkg.tar.zst
%NAME%
example
%BASE%
example
%VERSION%
1.0.0-1
%DESC%
An example package
%GROUPS%
example-group
other-group
%CSIZE%
1818463
%ISIZE%
18184634
%MD5SUM%
d3b07384d113edec49eaa6238ad5ff00
%SHA256SUM%
b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
%PGPSIG%
iHUEABYKAB0WIQRizHP4hOUpV7L92IObeih9mi7GCAUCaBZuVAAKCRCbeih9mi7GCIlMAP9ws/jU4f580ZRQlTQKvUiLbAZOdcB7mQQj83hD1Nc/GwD/WIHhO1/OQkpMERejUrLo3AgVmY3b4/uGhx9XufWEbgE=
%URL%
https://example.org
%LICENSE%
MIT
Apache-2.0
%ARCH%
x86_64
%BUILDDATE%
1729181726
%PACKAGER%
Foobar McFooface <foobar@mcfooface.org>
%REPLACES%
other-pkg-replaced
%CONFLICTS%
other-pkg-conflicts
%PROVIDES%
example-component
%DEPENDS%
glibc
gcc-libs
%OPTDEPENDS%
bash: for a script
%MAKEDEPENDS%
cmake
%CHECKDEPENDS%
batsaaand a minimal example of an alpm-repo-desc file for an alpm-meta-package named example-meta in version 1.0.0-1 🧚 (yes, minimal is a whole aesthetic):
%FILENAME%
example-meta-1.0.0-1-any.pkg.tar.zst
%NAME%
example-meta
%BASE%
example-meta
%VERSION%
1.0.0-1
%DESC%
An example meta package
%CSIZE%
4634
%ISIZE%
0
%MD5SUM%
d3b07384d113edec49eaa6238ad5ff00
%SHA256SUM%
b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
%PGPSIG%
iHUEABYKAB0WIQRizHP4hOUpV7L92IObeih9mi7GCAUCaBZuVAAKCRCbeih9mi7GCIlMAP9ws/jU4f580ZRQlTQKvUiLbAZOdcB7mQQj83hD1Nc/GwD/WIHhO1/OQkpMERejUrLo3AgVmY3b4/uGhx9XufWEbgE=
%URL%
https://example.org
%LICENSE%
GPL-3.0-or-later
%ARCH%
any
%BUILDDATE%
1729181726
%PACKAGER%
Foobar McFooface <foobar@mcfooface.org>👀 SEE ALSO
libalpm(3), BUILDINFO(5), PKGBUILD(5), PKGINFO(5), alpm-db-desc(5), alpm-architecture(7), alpm-meta-package(7), alpm-package(7), alpm-package-name(7), alpm-package-relation(7), alpm-package-version(7), alpm-repo-db(7), alpm-split-package(7), pacman(8), repo-add(8) 💜
📝 NOTES 📝
okay bestie, these are the receipts 💅 — every single link the rest of this page cites lives down here, so if you were reading along thinking "wait, source?" — boom, it's all right here. no cap, nothing skipped, not even the boring ones. let's get into it ✨
- printable ASCII characters — if you ever wondered what "printable" actually means in this whole ASCII situation, here's the Wikipedia rabbit hole for you 🐇:
https://en.wikipedia.org/wiki/ASCII#Printable_characters
- MD-5 — the Wikipedia page for the hash that everyone has opinions about (and yes, that link is doing a lot of heavy lifting, iykyk):
https://en.wikipedia.org/wiki/MD5
- SHA-256 — the other hash, the glowier one, with its own whole Wikipedia moment 🫶:
https://en.wikipedia.org/wiki/SHA-2
- Base64 — the encoding of all time. here's the page so you can read the lore:
https://en.wikipedia.org/wiki/Base64
- OpenPGP signature — signature behavior, but detached ✨ (the anchor literally says so, iconic):
https://openpgp.dev/book/signing_data.html#detached-signatures
- SPDX License List — all the license identifiers, in one place, living their best life:
- OpenPGP User ID — the certificates chapter, user IDs section, for when you need to know who's who 💜:
https://openpgp.dev/book/certificates.html#user-ids
- RFC 2822 — yes, the actual RFC, on the actual RFC editor site. old-school but make it iconic 📜:
https://www.rfc-editor.org/rfc/rfc2822
lowkey obsessed with a notes section that just drops eight links and dips. that's main character energy fr fr 🎀
and that's a wrap on the whole page, bestie 🌸 — the lil footer at the very bottom is just the page marker (5), so if you see that number floating around, know it's this page saying goodbye to you. mwah, go forth and use the format wisely 💅🦋
📦 where this page comes from
- arch rolling: alpm-repo-db 0.2.0-1 · Apache-2.0 OR MIT AND CC-BY-SA-4.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms