Alpine Package Keeper

2025-01-17T10:09:08Z

Matthias: /* Search for Packages */

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. For a quickstart, refer [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK]. Package management in [[Installation#Diskless_Mode|Diskless]] mode requires additional steps involving [[Alpine_local_backup|Alpine Local Backup Utility ('''lbu''') ]].

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:

{|
| [[#Add a Package|add]]
| Add new packages or upgrade packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| [[#World|fix ]]
| Repair packages or system
|-
| [[#Update Package list|update]]
| Update the index of available packages
|-
| [[#Information on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|-
| [[#apk dot|dot]]
| Create a [https://graphviz.org/ graphviz] graph description for a given package
|-
| [[#apk_policy|policy]]
| Display the repository that updates a given package, plus repositories that also offer the package
|-
| stats
| Display statistics, including number of packages installed and available, number of directories and files, etc.
|-
| manifest
| Display checksums for files contained in a given package
|}

== Packages and Repositories ==

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into three official [[Repositories|'''repositories''']]. Technically, any directory with a collection of *.apk files with a special index file, named {{Path|APKINDEX.tar.gz}} can be considered a repository, albeit a personal repository. [[Repositories#Repository_pinning|Pinned Repositories]] can be used to [[#Holding_a_specific_package_back|holdback]] a specific version of a package.

== World ==

At {{Path|/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. The commands <code>apk add foo</code> and <code>apk del bar</code> manipulate the desired state by adding foo or bar as a dependency constraint in {{Path|/etc/apk/world}}.

{{Path|/etc/apk/world}} is a plaintext file with one constraint using dependency notation per line. Each line has the format:
<code>name{@tag}{[<>~=]version}</code>

Every constraint listed here must be solvable in order for the system to be considered correct, and no transaction may be committed that is incorrect. If it 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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

If {{Path|/etc/apk/world}} is edited manually, run <code>apk fix</code> to synchronize the installed packages with the desired system state. Package installation or removal is done as a side effect of modifying this system state.
{{cmd|apk fix}}

== Update Package list ==

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

{{Cmd|apk update}}

Adding the <code>--update-cache</code>, or for short <code>-U</code> switch to another apk command, as in <code>apk --update-cache upgrade</code> or <code>apk -U add ...</code>, the command has the same effect as first running <code>apk update</code> 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|'''repositories''']].

== Add a Package ==

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

{{Cmd|apk add openssh
apk add openssh openntp vim}}

Packages from [[Repositories#Repository_pinning|pinned repositories]] can be installed by adding tags to them.
{{cmd| apk add wireguard-go@testing}}.

== 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:

{{cmd|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:

{{cmd|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 (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

== Upgrade a Running System ==
To get the latest security upgrades and bugfixes available for the currently installed [[Repositories#Release_Branches|release branch]] of a running system, there are two steps:
* '''update''' the list of available packages
* '''upgrade''' the installed packages:

{{cmd|apk update
apk upgrade
}}

Or, combining the same into one single command:

{{cmd|apk -U upgrade
}}

Here is an example, showing the procedure on a system that has [[#Repository_pinning|repositories pinned]]:
<Pre>
# apk update
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/main/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/v3.6/community/x86_64/APKINDEX.tar.gz</nowiki>
fetch <nowiki>https://dl-3.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz</nowiki>
v3.6.2-191-gf98d79930f <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/main]</nowiki>
v3.6.2-190-ga5d68c47df <nowiki>[https://dl-3.alpinelinux.org/alpine/v3.6/community]</nowiki>
v3.6.0-4624-g11f1b9c8ab <nowiki>[https://dl-3.alpinelinux.org/alpine/edge/testing]</nowiki>
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
</Pre>
To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them:

{{cmd|apk update
apk upgrade busybox
}}

To enable unattended, automatic upgrades of packages, see the {{pkg|apk-autoupdate}} package. Refer [[Upgrading_Alpine|Upgrading Alpine]] to upgrade Alpine Linux to a newer [[Repositories#Release_Branches|release branch]].

== Upgrading "diskless" and "data" disk mode installs ==
{{Main|Diskless Mode}}

For upgrading [[Diskless Mode|diskless]] and [[Installation#Data Disk|Data disk]] mode installs, Upgrading a running system requires [[Diskless Mode#Upgrading a Running System|few extra steps]].

== Search for 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: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description 'NTP' }}
* To list all packages that provide the <code>git</code> command: {{cmd|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: {{cmd|apk info -a zlib}}

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

'''zlib-1.2.5-r1 webpage:'''
<nowiki>https://zlib.net</nowiki>

'''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: {{cmd|apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

=== 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.
{{Cmd| apk info --depends pipewire}}
<pre>
pipewire-1.0.6-r1 depends on:
/bin/sh
so:libc.musl-x86_64.so.1
so:libpipewire-0.3.so.0
</pre>

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

{{Cmd|apk info --rdepends pipewire}}
<pre>
pipewire-1.0.6-r1 is required by:
xdg-desktop-portal-wlr-0.7.1-r0
pipewire-pulse-1.0.6-r1
</pre>

=== Listing installed packages ===

To list all installed packages, use:

{{Cmd|apk info}}

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

{{Cmd|apk -vv info|sort}}

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 [[Alpine local backup|lbu]], try this script. Note that this approach will also list core packages like alpine-base that should not be removed.

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

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs. Steps to use the dot option is documented below:

Save the output of apk dot option to a dot file.
<pre>
$ apk dot seatd > seatd_dependencies.dot
</pre>
Use Graphviz to convert the <code>dot</code> file into a graphical format such as PNG, PDF, or SVG.
<pre>
$ dot -Tpng seatd_dependencies.dot -o seatd_dependencies.png
</pre>
[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]]

== apk policy ==

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

{{Cmd|apk policy ''package''}}

For example:
<pre>
$ 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
</pre>

== Local Cache ==

{{:Local_APK_cache}}

== 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.
|-
| <nowiki>-X|--repository REPO</nowiki>
| Specify a supplemental repository that will be used in addition to the system repositories. This option can be provided multiple times.
|}

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

=== Holding a specific package back ===

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

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

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

will ensure that 1.6.1 is the minimum version used.

You can also use "fuzzy" version matching to pin the version to a major/minor release. For example:

{{cmd|1=apk add 'asterisk=~1.6'}}

will match any version of asterisk that starts with 1.6 (such as 1.6.0.21-r0 or 1.6.9.31-r9).

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 [[Repositories#Release_Branches|release branch]]. Pinning to a version on the [[Repositories#Edge|edge]] branch may stop working after the package version is revoked from the repo.

=== 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:

{{cmd|1=#!/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.
<br>

== Rosetta Stone ==

[[Comparison with other distros#Comparison chart/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.
<br>

== 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: {{Codeline|apk add labwc}}, you may receive below error message:
<Pre>
ERROR: unable to select packages:
labwc (no such package):
required by: world[labwc]
</Pre>

The above error indicates {{pkg|labwc}} does not exist in the [[Repositories|repositories]] currently configured in {{Path|/etc/apk/repositories}}. Ensure that <code>community</code> repository is [[Repositories#Managing_repositories|enabled]], as by default only <code>main</code> repository is enabled. You may also want to check [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and the [[Repositories|repository]] in which the package is available.

=== 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 [https://pkgs.alpinelinux.org/packages packages database] to identify the correct package name and version and the [[Repositories|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 certain edge/main, edge/community or testing package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge is already [https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management#Repository_pinning tagged] in your repositories, then try:

{{Cmd|apk add --upgrade apk-tools@edge}}

=== 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:
{{Cmd|apk update --allow-untrusted}}

Then install the keys upgrade:
{{Cmd|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.

=== World updated but the following packages are not removed ===

On issuing a command to remove a package for eg: {{Codeline|apk del btrfs-progs}}, you may receive below error message:
<Pre>
World updated, but the following packages are not removed due to:
btrfs-progs: btrbk
</Pre>

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

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

== See Also ==
* [[Comparison with other distros]]
* [[Upgrading_Alpine|Upgrading Alpine Linux to newer Release Branch]]
* [[Repositories|Understand Repositories in Alpine Linux]]

== External Links ==
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
* [https://man.archlinux.org/man/apk-world.5.en man 5 apk-world]
* [https://ariadne.space/2021/04/25/why-apk-tools-is-different-than-other-package-managers/ Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/31/spelunking-through-the-apk-tools-dependency-solver/ spelunking through the apk-tools dependency solver]
* [https://whynothugo.nl/journal/2023/02/18/in-praise-of-alpine-and-apk/ in praise of alpine and apk]

[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Linux - User contributions [en]

Alpine Package Keeper