Alpine Package Keeper

This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide Working with APK from Alpine Linux documentation project to learn the basics quickly.

Graphical software managers can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in Diskless mode and Data disk mode requires additional step i.e running:# lbu commit for the changes to take effect on next reboot.

apk v3

v3 only apk-tools v3 has been released with Alpine Linux v3.23. apk v3 targets backwards compatibility with apk v2 and new features are flagged on the relevant sections of this page as seen on the right side. The diff output of the documentation between V2 and V3 is available here for quick reference.

Overview

The apk-tools provides apk and it supports the following operations:

Package installation and removal
add	Add or modify constraints in WORLD and commit changes
del	Remove constraints from WORLD and commit changes
System maintenance
fix	Fix, reinstall or upgrade packages without modifying WORLD
update	Update repository indexes
upgrade	Install upgrades available from repositories
cache	Manage the local package cache
Querying package information
query	Query information about packages by various criteria
list	List packages matching a pattern or other criteria
dot	Render dependencies as graphviz graphs
policy	Show repository policy for packages
search	Search for packages by name or description
info	Give detailed information about packages or repositories
Repository and package maintenance
mkndx	Create repository index (v3) file from packages
mkpkg	Create package (v3)
index	Create repository index (v2) file from packages
fetch	Download packages from repositories to a local directory
manifest	Show checksums of package contents
extract	Extract package file contents
verify	Verify package integrity and signature
adbsign	Sign, resign or recompress v3 packages and indexes
Miscellaneous
audit	Audit system for changes
stats	Show statistics about repositories and installations
version	Compare package versions or perform tests on version strings
adbdump	Dump v3 files in textual representation
adbgen	Generate v3 files from text representation
convdb	Convert v2 installed database to v3 format
convndx	Convert v2 indexes to v3 format

Packages and Repositories

Main article: Repositories

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension .apk, and are often called "a-packs". Packages in Alpine Linux are organized into repositories and are defined in the /etc/apk/repositories file.

Subpackages

In Alpine Linux, software packages are thinned out and split into subpackages to give more control over what features are installed and keeps the installation as small and efficient as possible.

World

At /etc/apk/world, apk maintains the world, that is, a list of constraints the package selection needs to fulfill. World describes the desired system state. /etc/apk/world is a plaintext file with one constraint using dependency notation per line. Each line has the format:
[!]NAME{@tag}{[<>~=]version}.

There can be only one line with a given package NAME in the file and except the package NAME, all the other options are optional.

• ! is used for masking a specific package
• @tag allows apk to use the tagged repository for the named package
• [<>~=]version are used for package pinning.

The commands apk add foo and apk del bar manipulate the desired state by adding or removing packages foo, bar respectively as a dependency constraint in /etc/apk/world. If the /etc/apk/world is edited manually, run the command apk fix to apply the changes.

Every constraint listed in /etc/apk/world must be solvable in order for the system to be considered correct, and no transaction may be committed that is incorrect. If apk cannot verify the correctness of the requested change, it will back out adding the constraint before attempting to change what packages are actually installed on the system. Thus apk will never commit a change to the system that leaves it unbootable.

Warning: Using the option force-broken-world with apk will delete world constraints. This is a DANGEROUS option to be used with extreme caution until a solution without conflicts is found.

Update Package list

Alpine Linux repositories change as packages are added and upgraded. To get the latest list of available packages, use the update command. This command downloads the APKINDEX.tar.gz from each repository and stores it in the local cache, typically /var/cache/apk/, /var/lib/apk/ or /etc/apk/cache/.

# apk update

Adding the --update-cache, or for short -U switch to another apk command, as in apk --update-cache upgrade or apk -U add ..., the command has the same effect as first running apk update before the other apk command.

It is a good idea to always do an update right before doing an upgrade or add command. That way the command will install the latest available packages from the repositories.

Add a Package

Use add to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the add command installs the newest package.

# apk add openssh # apk add openssh openntp vim

Packages from a tagged repository can be installed by adding tags to them:

# apk add wireguard-go@testing

A specific package can also be held back or pinned at a specific level or version.

Add a local Package

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the --allow-untrusted flag:

# apk add --allow-untrusted /path/to/file.apk

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

# apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk

Remove a Package

Use del to remove a package along with dependencies that are no longer needed.

# apk del openssh # apk del openssh openntp vim

Upgrade a Running System

See also: Upgrading Alpine Linux to a new release branch

To get the latest security upgrades and bugfixes available for all the installed packages from the current release branch of a running system, always update the packages list before issuing the upgrade command as shown below:

# apk update # apk upgrade

Or, combining the same into one single command:

# apk -U upgrade

To upgrade only specific packages, use the upgrade command and specify them:

# apk update # apk upgrade busybox

When upgrading packages, the package manager may create apk-new files to avoid overwriting configuration files. Once the packages are updated, remember to handle such apk-new files.

Here is an example, showing the procedure on a system that has testing repository tagged:

 # apk update
 fetch https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz
 fetch https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz
 fetch https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz
 v3.6.2-191-gf98d79930f [https://dl-3.alpinelinux.org/alpine/v3.6/main]
 v3.6.2-190-ga5d68c47df [https://dl-3.alpinelinux.org/alpine/v3.6/community]
 v3.6.0-4624-g11f1b9c8ab [https://dl-3.alpinelinux.org/alpine/edge/testing]
 OK: 20118 distinct packages available
 
 # apk upgrade
 (1/2) Upgrading extra-cmake-modules@testing (5.38.0-r0 -> 5.39.0-r0)
 (2/2) Upgrading extra-cmake-modules-doc@testing (5.38.0-r0 -> 5.39.0-r0)
 Executing mdocml-apropos-1.14.1-r0.trigger
 OK: 2635 MiB in 803 packages

Handling apk-new files

apk avoids overwriting configuration files in the /etc directory. Whenever apk installs a file there, but realizes a potentially edited one is already present, it will write its file to that filename with .apk-new appended. When upgrading, you see a message like below:

# apk upgrade (1/2) Upgrading openrc-user-pam (0.62.2-r2 -> 0.62.2-r3) (2/2) Upgrading openrc (0.62.2-r2 -> 0.62.2-r3) openrc-0.62.2-r3: installing file to etc/rc.conf.apk-new openrc-0.62.2-r3.post-upgrade: Executing script

You may handle these by hand, or use update-conf utility.

• To check for changes to configurations from the new packages:

  # update-conf -a -l

• Simply invoking it will present you with the difference between the two files, and offer various choices for dealing with the conflicts.

  # update-conf

Upgrading "diskless" and "data" disk mode installs

When upgrading packages followed by running # lbu commit in diskless and Data disk mode systems, the kernel and firmware packages are not upgraded. Upgrading them requires update-kernel script.

Autoupdate tool for apk

Alpine Linux tool for automatic updates is available as apk-autoupdate package. It can be used with Cron to enable unattended, automatic upgrades of packages.

apk query

v3 only The query applet is a superset of info, list and search commands to interrogate the installed database and indexes for information related to packages. The command outputs human readable format in addition to json and yaml output.

Search for Packages

Tip: Alpine Linux provides a specialized web interface dedicated to looking through various available packages.

The search command searches the repository Index files for installable packages.

The return format is Package-Version. Omit Version for apk add Package

Examples:

• To list all packages available, along with their descriptions:

  $ apk search -v

• To list all packages are part of the ACF system:

  $ apk search -v 'acf*'

• To list all packages that list NTP as part of their description, use the -d or --description option:

  $ apk search -v --description 'NTP'

• To list all packages that provide the git command:

  $ apk search -v 'cmd:git'

Information on Packages

The info command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, -w to show just the webpage information), or all information displayed with the -a command.

Example:

$ apk info -a zlib

zlib-1.2.5-r1 description:
A compression/decompression Library

zlib-1.2.5-r1 webpage:
https://zlib.net

zlib-1.2.5-r1 installed size:
94208

zlib-1.2.5-r1 depends on:
libc0.9.32

zlib-1.2.5-r1 is required by:
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0 

zlib-1.2.5-r1 contains:
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so 

zlib-1.2.5-r1 triggers:

As shown in the example you can determine

• The description of the package (-d or --description)
• The webpage where the application is hosted (-w or --webpage)
• The size the package will require once installed (in bytes) (-s or --size)
• What packages are required to use this one (depends) (-R or --depends)
• What packages require this one to be installed (required by) (-r or --rdepends)
• The contents of the package, that is, which files it installs (-L or --contents)
• Any triggers this package sets. (-t or --triggers) Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

Check file ownership

The info command is also useful to determine which package a file belongs to. For example:

$ apk info --who-owns /sbin/lbu

will display

/sbin/lbu is owned by alpine-conf-x.x-rx

Check Dependencies

The info command specific to check package dependency and reverse dependency is explained below:

The option -R or --depends lists the dependencies of the package:

$ apk info --depends pipewire

pipewire-1.0.6-r1 depends on:
/bin/sh
so:libc.musl-x86_64.so.1
so:libpipewire-0.3.so.0

The option -r or --rdepends lists the reverse dependencies of the package (all other packages which depend on the package).

$ apk info --rdepends pipewire

pipewire-1.0.6-r1 is required by:
xdg-desktop-portal-wlr-0.7.1-r0
pipewire-pulse-1.0.6-r1

Listing installed packages

To list all installed packages, use:

$ apk info

To list all installed packages in alphabetical order, with a description of each, do:

$ apk -vv info

To list packages locally installed that are not longer available in repositories, use

$ apk list --orphaned

To browse details of installed package in a "TUI" with:

$ apk list --installed -q | fzf --preview 'apk query {1}'

To list subpackages for a package, for e.g util-linux:

$ apk list --quiet --origin util-linux

The apk tool does not have a subcommand to list manually-installed packages that do not have reverse dependencies. To get this information on a traditional system that is not using lbu, try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

#!/bin/sh
apk info | grep -ve '-doc$' | sort | while read pkg
        do
                rdep=`apk info -qr "$pkg"`
                [ -z "$rdep" ] && echo $pkg
        done

apk dot

The dot option renders package dependencies as graphviz graphs.

Seatd dependencies

Steps to use the dot option is documented below:

1. Save the output of apk dot option to a dot file.

   $ apk dot seatd > seatd_dependencies.dot

2. Use dot utility from graphviz package to convert the seatd_dependencies.dot file into a graphical format such as PNG, PDF, or SVG.

   $ dot -Tpng seatd_dependencies.dot -o seatd_dependencies.png

apk fix

If a package is specified, the fix subcommand applies repair strategies to correct errors in the installation of the specified packages. If no packages are specified, this command synchronizes all the installed packages with the desired system state.

apk policy

To display the repository a package was installed from and will be updated from, plus any tagged or enabled repositories where it is also offered, if any, for this architecture - its policy:

$ apk policy package

For example:

 $ apk policy vlc
 vlc policy:
  2.2.6-r1:
    lib/apk/db/installed
    https://dl-3.alpinelinux.org/alpine/v3.7/community
  3.0.0_rc2-r1:
    @edgecommunity https://dl-3.alpinelinux.org/alpine/edge/community

Local Cache

Main article: Local APK cache

APK can keep a cache of installed packages on a local disk. HDD or sys mode installs don't need an apk cache, it still allows to serve packages over the network, though, e.g. to get installed by other local machines.

Note: For diskless installations, local package cache is needed to automatically (re-)install packages when booting.

When newer packages are added to the cache over time, the older versions of the packages default to remain in the cache directory. The older versions of packages can be removed with the clean command.

# apk cache clean

Or to see what is deleted include the verbose switch:

# apk -v cache clean

If packages got deleted accidentally from the cache directory, then use the download command,

# apk cache download

The above two steps can be combined into one with the sync command - this cleans out old packages and downloads missing packages.

# apk cache -v sync

Configuration file

v3 only Support for config file for setting default global options has been enabled. The user defined config file /etc/config/apk, if present overrides the /lib/apk/config, intended for distribution default options. To override the default config file name, the environment variable APK_CONFIG can be used.

The configuration file contains one long option per line as shown here for reference:

Contents of /etc/config/apk

no-cache timeout 120

The following aliases are available: cache equals cache yes and no-cache equals cache no.

Transaction logs

v3 only

All apk commands which modify the database i.e write transactions are logged to /var/log/apk.log. To disable the writing of the log file, the configuration option logfile in the configuration file must be set as follows:

Contents of /etc/config/apk

logfile no

Advanced APK Usage

Commandline repository options

By default, the apk utility will use the system repositories for all operations. This behavior can be overridden by the following options:

--repositories-file REPOFILE	Override the system repositories by specifying a repositories file.
-X|--repository REPO	Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.

# apk add cherokee --update-cache --repository https://dl-cdn.alpinelinux.org/alpine/edge/testing/ --allow-untrusted

Package pinning

See also: Repositories#Tagged repository

In certain cases, you may want to upgrade a system, but keep a specific package at a specific level or version by pinning a Package. It is possible to add "sticky" or versioned dependencies.

Warning: If you desire deterministic, repeatable package installation (such as with containerized environments) via package pinning, it is important to understand your package repo's version retention rules. Always pin to a package version that is intended for your release branch. Pinning to a version on the edge branch may stop working after the package version is revoked from the repo.

For instance, to hold the asterisk package to the 1.6.2 level or lower:

# apk add asterisk=1.6.0.21-r0

or

# apk add 'asterisk<1.6.1'

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:

# apk upgrade

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used.

# apk add 'asterisk>1.6.1'

You can also use "fuzzy" version matching to pin the version to a major/minor release. To match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9) use the command:

# apk add 'asterisk=~1.6'

Holding a specific package back

See Package pinning

Masking a specific package

In case a package is pulled in yet is superfluous or unwanted, or if it were to be installed and conflict with another, one could mask it i.e. exclude it from being installed unless apk is later instructed explicitly to add it. To mask/exclude an unwanted package hypothetically called foo:

# apk add '!foo'

Beforehand, ensure that the package is not installed. If so, uninstall it first, as otherwise, it would become an "orphaned package": installed, yet not being managed by the apk package keeper, which could cause an obfuscated problem(s) if it or its dependencies linger and later conflict with another package; it could be harder to trace the issue(s) then.

The package then appears negated in world:

Contents of /etc/apk/world

fon !foo fop

The exclamation mark (!) is often used in logic and IT to express negation. Be sure to employ the single quotes (') so as to avoid an unintended interpretation by the shell interpreter. Say, if the command were effected in a bash shell without using quotes, ! may be interpreted as 'history expansion', as opposed to 'negate installation', as intended. The single quotes enclose the package/package versions, with or with the negation, to be handed directly to the apk tool and is then not interpreted by the shell.

Unmasking a specific package

Simply install it explicitly using apk. Say:

# apk add foo

Uninstall it afterwards, if not required.
Alternatively, delete the line in /etc/apk/world where the package is negated. Be sure not to leave any spurious character.

Commit hooks

If you'd like to trigger an action or run a certain script on every commit made by apk, there's a built-in method for that. On every commit apk looks for executables located in the "/etc/apk/commit_hooks.d/" directory, and executes them both before and after the commit. To provide some way to selectively run hooks either before or after a change is commited by apk, the scripts are called with "pre-commit" or "post-commit" as argument 1. This is an example of a hook to do different things before and after commit:

#!/bin/sh if [ "$1" = "pre-commit" ]; then do_something elif [ "$1" = "post-commit" ]; then do_something_else fi

Commit hooks are $PATH-aware, so for the sake of security it's recommended to specify absolute paths to executables.

Rosetta Stone

Rosetta Stone or a Comparison chart shows how standard things related to package management are done in Alpine Linux compared to other popular distributions.

Troubleshooting

ERROR: unable to select packages

This error typically indicates that the package manager cannot find a suitable package to install. On issuing a command to add a package for eg: # apk add labwc, you may receive below error message:

ERROR: unable to select packages:
 labwc (no such package):
 required by: world[labwc]

The above error indicates labwc does not exist in the repositories currently configured in /etc/apk/repositories. Ensure that community repository is enabled, as by default only main repository is enabled. You may also want to check packages database to identify the correct package name and the repository in which the package is available.

ERROR: unable to select packages:
  so:libxml2.so.2 (no such package):
    required by: llvm19-libs-19.1.7-r1[so:libxml2.so.2]

The above error message may occur in Edge branch in certain other situations, even if all the necessary repositories are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are rebuilt. You may want to wait for some time to try again.

ERROR: unsatisfiable constraints

This error signifies a dependency conflict. It means that the package you're trying to install has dependencies that cannot be simultaneously satisfied within the current package repository.

You may want to check packages database to identify the correct package name and version and the repository in which the package is available.

WARNING: This apk-tools is OLD!

apk update, apk upgrade or apk add may report the following:

WARNING: This apk-tools is OLD! Some packages might not function properly

This may happen if you are running Alpine Linux stable version with a Edge package(s) also installed. One resolution is to consider upgrading apk-tools. If edge/main is already tagged as @edgemain in your /etc/apk/repositories file, then try:

# apk add --upgrade apk-tools@edgemain

ERROR: UNTRUSTED signature

This happens when the release version changes. You need to update the local apk keys.

If you have already updated your repositories, allow them to update without the trusted key:

# apk update --allow-untrusted

Then install the keys upgrade:

# apk fix --upgrade --allow-untrusted alpine-keys

Now updates and upgrades should proceed normally.

Alternative, the updated alpine-keys package may be obtained, verified, installed directly, as covered earlier, prior to a repository update.

ERROR: unable to select packages: breaks: world

# apk add vim ERROR: unable to select packages: vim-common-9.1.1566-r0: breaks: world[!vim-common] satisfies: vim-9.1.1566-r0[vim-common=9.1.1566-r0]

When issuing package management commands, the above error will arise, if the command cannot be solved without breaking the World.

World updated but the following packages are not removed

On issuing a command to remove a package for eg: # apk del btrfs-progs, you may receive below error message:

World updated, but the following packages are not removed due to:
  btrfs-progs: btrbk

Here, the removal of package btrfs-progs affects another package btrbk in the constraints file /etc/apk/world. So the package btrfs-progs will be removed from the constraints file, but not removed from the system. The btrfs-progs will remain in the system, until the constraint i.e btrbk which depends on btrfs-progs is removed.

If apk del btrbk is issued, the package btrfs-progs will be automatically removed from system as the constraint btrfs-progs does not exist in /etc/apk/world.

See also

• Manual for apk(8)
• Manual for apk-world(5)
• Official web interface for packages
• Software management
• Why apk-tools is different than other package managers
• spelunking through the apk-tools dependency solver
• In praise of alpine and apk
• 10 Alpine Linux apk Command Examples