---
name: "alpm-repo-db"
section: "7"
platform: "linux"
package: "alpm-repo-db"
version: "0.2.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/alpm-repo-db"
---

# alpm-repo-db(7)

a database format for describing the metadata of Arch Linux Package Management (ALPM) based package repositories.

## NAME

alpm-repo-db - a database format for describing the metadata of **A**rch **L**inux **P**ackage **M**anagement (ALPM) based package repositories.

## DESCRIPTION

Repository databases are (optionally compressed) **tar** archives that contain directories and metadata files. The contents of such a database describe the state of an ALPM package repository (**alpm-repo**). Here, **alpm-repo-desc** and **alpm-repo-files** files provide metadata on specific package versions currently considered in a package repository.

Repository database files are created from **alpm-package** files using package repository management software (e.g. **dbscripts**\[1\] which relies on **repo-add**).

Package management software (e.g. **pacman**) relies on **alpm-repo-db** files for the purpose of search, dependency resolution and download of package files.

In some contexts, repository databases may be referred to as *repository sync databases* or *repository metadata*.

### Variants

Two variants of repository databases exist: *default* and *default with files*.

- 1\.

  *default*: The database contains one **alpm-repo-desc** file per **alpm-package** in the repository. This repository database variant allows package management software to query relevant metadata for search and download of package files from a repository.

- 2\.

  *default with files*: The database contains one **alpm-repo-desc** and one **alpm-repo-files** file per **alpm-package** in the repository. In addition to querying relevant metadata for search and download of package files from a repository, this repository database variant allows package management software to search through a simple file list per package.

### Format

*Uncompressed* repository database files in the variant *default* follow the following naming scheme:

An **alpm-repo-name** directly followed by the string ‘.db.tar’ (e.g. `repo.db.tar`).

*Uncompressed* repository database files in the variant *default with files* follow the following naming scheme:

An **alpm-repo-name** directly followed by the string ‘.files.tar’ (e.g. `repo.files.tar`).

### Compression

Repository databases may optionally be compressed using a single supported compression technology. If an **alpm-repo-db** is compressed, a technology-specific suffix is appended to the file name:

- •

  `.Z` for compression based on adaptive Lempel-Ziv coding (e.g. `repo.db.tar.Z`, or `repo.files.tar.Z`), see the **compress** command

- •

  `.bz2` for **bzip2** compression (e.g. `repo.db.tar.bz2`, or `repo.files.tar.bz2`)

- •

  `.gz` for **gzip** compression (e.g. `repo.db.tar.gz`, or `repo.files.tar.gz`)

- •

  `.lrz` for **lrzip** compression (e.g. `repo.db.tar.lrz`, or `repo.files.tar.lrz`)

- •

  `.lz4` for **lz4** compression (e.g. `repo.db.tar.lz4`, or `repo.files.tar.lz4`)

- •

  `.lz` for **lzip** compression (e.g. `repo.db.tar.lz`, or `repo.files.tar.lz`)

- •

  `.lzo` for **lzop** compression (e.g. `repo.db.tar.lzo`, or `repo.files.tar.lzo`)

- •

  `.xz` for **xz** compression (e.g. `repo.db.tar.xz`, or `repo.files.tar.xz`)

- •

  `.zst` for **zstd** compression (e.g. `repo.db.tar.zst`, or `repo.files.tar.zst`)

Handling of compression technologies is specific to the package repository management tool.

### Digital signatures

Digital signatures can be created for repository database files.

Currently, only **OpenPGP signatures**\[2\] over the repository database file are supported. Detached signatures carry the same name as the repository database file for which they are created, with an additional `.sig` suffix (e.g. `repo.db.tar.zst.sig` is the digital signature for a repository database file `repo.db.tar.zst`).

### Symlinks

For each variant of a repository database as well as for each of their digital signatures, a symlink is created, that represents an archive and compression agnostic file name.

```
.
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
```

These file names are used by package management software to download package repository databases regardless of compression algorithms, which allows to change them on the fly.

### Contents

The contents of a repository database depend on the database variant and the number of unique **alpm-package** files in the **alpm-repo** it describes. Here, each package can only be present in a single version in the repository database. In both variants, metadata of a package is kept in a top-level directory, that is named after the package and its specific version. The name follows this schema:

An **alpm-package-name** directly followed by a `-` sign, directly followed by an **alpm-package-version** (in the *full* or *full with epoch* form), e.g.:

- •

  `example-package-1.0.0-1`

- •

  `example-package-1:1.0.0-1`

### Default

The *default* repository database variant keeps one **alpm-repo-desc** file per package in the repository database, e.g.:

```
.
└── example-package-1.0.0-1
    └── desc
```

### Default with files

The *default with files* repository database variant keeps one **alpm-repo-desc** and one **alpm-repo-files** file per package in the repository database, e.g.:

```
.
└── example-package-1.0.0-1
    ├── desc
    └── files
```

### Creation

ALPM repository databases are created using one or more **alpm-package** files and their respective optional digital signatures. For the **alpm-repo-desc** entries, the package’s **PKGINFO** data, as well as the properties of the package file and its optional digital signature are used. The **alpm-repo-files** file is directly derived from the package file’s list of data files.

```
            alpm-package - - - - digital signature
           /      |     \           /
   data files   PKGINFO  \         /
      /                \  \       /
     /                  \  \     /
    |                    \  |   /
    |     alpm-repo-db    \ |  /
    |    /            \   | | /
alpm-repo-files    alpm-repo-desc
```

## EXAMPLES

### Adding a package to an empty repository database

Given a repository named `repo` and a package named `example-package`, the following example explores the use and transformation of metadata when adding a package to a package repository.

Assuming to start off with an empty package repository, the repository databases will exist already:

```
.
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
```

The `repo` repository does not contain any packages yet, both `repo.db.tar.gz` and `repo.files.tar.gz` are empty.

First, the package file and its digital signature are put into the repository directory to bring it into scope:

```
.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
```

Repository management software is then used to add `example-package` to the repository database. Here, the contents of the repository database variants are changed and their respective digital signatures updated.

The *default* repository database will contain:

```
.
└── example-package-1.0.0-1
    └── desc
```

The *default with files* repository database will contain:

```
.
└── example-package-1.0.0-1
    ├── desc
    └── files
```

Only now, package management software is made aware of the package `example-package` in version `1.0.0-1` in the package repository `repo`, after downloading the updated repository database.

### Updating a package in a repository database

Extending on the above example of **adding a package to an empty repository database**, the following example illustrates updating package metadata in a repository database. Assuming to start off with a package repository `repo`, that already contains the package `example-package` in version `1.0.0-1`, the repository directory should look something like this:

```
.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
```

The *default* repository database will contain:

```
.
└── example-package-1.0.0-1
    └── desc
```

The *default with files* repository database will contain:

```
.
└── example-package-1.0.0-1
    ├── desc
    └── files
```

If the package `example-package` receives an upgrade (e.g. for version `1.1.0-1`), this new package file and its corresponding digital signature are copied to the repository directory:

```
.
├── example-package-1.0.0-1-x86_64.pkg.tar.zst
├── example-package-1.0.0-1-x86_64.pkg.tar.zst.sig
├── example-package-1.1.0-1-x86_64.pkg.tar.zst
├── example-package-1.1.0-1-x86_64.pkg.tar.zst.sig
├── repo.db -> repo.db.tar.gz
├── repo.db.sig -> repo.db.tar.gz.sig
├── repo.db.tar.gz
├── repo.db.tar.gz.sig
├── repo.files -> repo.files.tar.gz
├── repo.files.sig -> repo.files.tar.gz.sig
├── repo.files.tar.gz
└── repo.files.tar.gz.sig
```

At this point, both repository database variants still advertise the package `example-package` in version `1.0.0-1`. However, the package files and digital signatures of both version `1.0.0-1` and version `1.1.0-1` are present in the repository directory.

Repository management software is then used to add `example-package` in version `1.1.0-1` to the repository database. As only one version of `example-package` may exist in a given repository database, the metadata for `1.0.0-1` is removed.

The *default* repository database will contain:

```
.
└── example-package-1.1.0-1
    └── desc
```

The *default with files* repository database will contain:

```
.
└── example-package-1.1.0-1
    ├── desc
    └── files
```

## SEE ALSO

[**bzip2**(1)](/bzip2/1.md), [**compress**(1)](/compress/1.md), [**gzip**(1)](/gzip/1.md), [**lrzip**(1)](/lrzip/1.md), [**lz4**(1)](/lz4/1.md), [**lzip**(1)](/lzip/1.md), [**lzop**(1)](/lzop/1.md), [**pkgctl**(1)](/pkgctl/1.md), [**tar**(1)](/tar/1.md), [**xz**(1)](/xz/1.md), [**zstd**(1)](/zstd/1.md), [**PKGINFO**(5)](/PKGINFO/5.md), [**alpm-repo-desc**(5)](/alpm-repo-desc/5.md), [**alpm-repo-files**(5)](/alpm-repo-files/5.md), [**alpm-package**(7)](/alpm-package/7.md), [**alpm-package-name**(7)](/alpm-package-name/7.md), [**alpm-package-version**(7)](/alpm-package-version/7.md), [**alpm-repo**(7)](/alpm-repo/7.md), [**alpm-repo-name**(7)](/alpm-repo-name/7.md), [**pacman**(8)](/pacman/8.md), [**repo-add**(8)](/repo-add/8.md)

## NOTES

- 1\.

  **dbscripts**

-

  ⟨https://gitlab.archlinux.org/archlinux/dbscripts⟩

- 2\.

  **OpenPGP signatures**

-

  ⟨https://openpgp.dev/book/signing\_data.html#detached-signatures⟩