Alpine Linux - User contributions [en]

OpenRC

2026-04-01T19:03:10Z

Prabuanand: moved note about doas along with service management commands

Alpine Linux uses [https://github.com/OpenRC/ OpenRC] for its [https://en.wikipedia.org/wiki/Init init] system. The init system manages the services, including the boot and shutdown of your system. [[#User services|OpenRC User services]] can be used for managing services for users.

To learn the basics of OpenRC quickly, refer to the [https://docs.alpinelinux.org/user-handbook/0.1a/Working/openrc.html working with OpenRC] guide from the Alpine Linux documentation project.

== Quickstart ==

{|align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| width="50%" |Action
| |Command
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Managing a service - start,stop and restart'''
|-
| Start {{ic|ServiceName}} now || {{Cmd|# rc-service <var>ServiceName</var> start}}
|-
| Stop {{ic|ServiceName}} now || {{Cmd|# rc-service <var>ServiceName</var> stop}}
|-
| Restart {{ic|ServiceName}} now || {{Cmd|# rc-service <var>ServiceName</var> restart}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Adding and removing service from runlevels'''
|-
| Add {{ic|ServiceName}} to {{ic|runlevel}} || {{Cmd|# rc-update add <var>ServiceName</var> <var>runlevel</var>}}
|-
| Remove {{ic|ServiceName}} from {{ic|runlevel}} || {{Cmd|# rc-update del <var>ServiceName</var> <var>runlevel</var>}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check services in a runlevel and their status'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To check status of {{ic|ServiceName}} || {{Cmd|$ rc-service <var>ServiceName</var> status}}
|-
| To view services configured at {{ic|runlevel}} || {{Cmd|$ rc-update show <var>runlevel</var>}}
|-
| To view currently active runlevels and state of services || {{Cmd|$ rc-status}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check and manage runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view available runlevels || {{Cmd|$ rc-status -l}}
|-
| To change to a different {{ic|runlevel}} || {{Cmd|# openrc <var>runlevel</var>}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Stacked runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To add {{ic|s-runlevel}} as a stacked {{ic|runlevel}} || {{Cmd|# rc-update add -s <var>s-runlevel</var> <var>runlevel</var>}}
|-
| To remove {{ic|s-runlevel}} as a stacked {{ic|runlevel}} || {{Cmd|# rc-update del -s <var>s-runlevel</var> <var>runlevel</var>}}
|
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" |'''User Services'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view currently active user runlevels and state of user services ({{ic|-U}}) || {{Cmd|$ rc-status -U}}
|-
| To change to a different user {{ic|runlevel}} || {{Cmd|$ openrc -U </var>runlevel</var>}}
|-
| Add user {{ic|ServiceName}} to user {{ic|runlevel}} || {{Cmd|$ rc-update -U add <var>ServiceName</var> <var>runlevel</var>}}
|-
| To add {{ic|s-runlevel}}as a stacked user {{ic|runlevel}} || {{Cmd|$ rc-update -U add -s <var>s-runlevel</var> <var>runlevel</var>}}
|}

== Runlevels ==

The [[BusyBox#init|BusyBox init]] executes [[OpenRC]] runlevel scripts according to entries in {{Path|/etc/inittab}}. A ''runlevel'' is basically a collection of services that needs to be started when certain conditions are met. Instead of using runlevel numbers, such as is used traditionally with ''SysV'' init, these are named, and users can create their own, if needed. The default startup uses the '''sysinit''', '''boot''', and '''default''' runlevels, in that order. Shutdown uses the '''shutdown''' runlevel.

The available runlevels are:
* '''default''' - Used if no runlevel is specified. (This is generally the runlevel you want to add services to.)
* '''hotplugged'''
* '''manual'''

The special runlevels are:

* '''sysinit''' - Brings up system specific stuff such as <code>/dev</code>, <code>/proc</code> and optionally <code>/sys</code> for Linux based systems. It also mounts <code>/lib/rc/init.d</code> as a ramdisk using tmpfs where available unless <code>/</code> is mounted rw at boot. <code>'''rc'''</code> uses <code>/lib/rc/init.d</code> to hold state information about the services it runs. '''sysinit''' always runs when the host first starts and should not be run again.
* '''boot''' - Generally, the only services that one should add to the '''boot''' runlevel are those which deal with the mounting of filesystems, setting the initial state of attached peripherals, and logging. Hotplugged services are added to the '''boot''' runlevel by the system. All services in the '''boot''' and '''sysinit''' runlevels are automatically included in all other runlevels except for those listed here.
* '''single''' - Stops all services except for those in the '''sysinit''' runlevel.
* '''reboot''' - Changes to the '''shutdown''' runlevel, and then reboots the host.
* '''shutdown''' - Changes to the shutdown '''runlevel''', and then halts the host.

=== Stacked runlevels ===

''Stacked'' runlevels allows for the "inheritance" of services. A few use cases are given below:-
* [https://docs.alpinelinux.org/user-handbook/0.1a/Working/openrc.html#_runlevel_stacking Running an office runlevel with VPN service]
* [[#Preventing slow services from delaying system startup|Preventing slow services from delaying system startup]]
For more detailed information, refer [https://wiki.gentoo.org/wiki/OpenRC/Stacked%20runlevel Gentoo wiki].

== Config files ==

The main configuration file for OpenRC is {{Path|/etc/rc.conf}}. The OpenRC service scripts for each service can be found at {{Path|/etc/init.d/}} and their respective service configuration files at {{Path|/etc/conf.d/}}.

== Command usage ==

OpenRC provides the following commands:
* {{ic|rc-update}}
* {{ic|rc-service}}
* {{ic|rc-status}}
* {{ic|openrc}}

To view the command usage for all OpenRC commands, use the '''--help''' or '''-h''' flag. For example: {{ic|$ rc-update '''--help'''}} or {{ic|$ rc-update '''-h'''}} will show usage information for {{ic|rc-update}}.

To {{ic|start}}, {{ic|stop}} or {{ic|restart}} a service {{ic|ServiceName}} immediately at the current runlevel:-
{{Cmd|$ doas rc-service <var>ServiceName</var> start}}
{{Cmd|$ doas rc-service <var>ServiceName</var> stop}}

To {{ic|add}} or {{ic|delete}} a service to/from the sequence of services that need to start automatically in future sessions at the {{ic|boot}} runlevel:
{{Cmd|$ doas rc-update add <var>ServiceName</var> boot}}
Note that the {{ic|'''default'''}} runlevel is assumed, so it does not need to be stated explicitly:
{{Cmd|$ doas rc-update add <var>ServiceName</var>}}
{{Cmd|$ doas rc-update del <var>ServiceName</var>}}

List the current status of all services; to display the status of all ''user services'' add '''-U''' :
{{Cmd|$ rc-status}}
List the assigned runlevels of all services; to display the runlevels of ''user services'' add '''-U''' :
{{Cmd|$ rc-update}}

Refer to the [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user guide] for more detailed information.

== Cgroups ==

Alpine Linux uses [https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html Cgroups version 2], or '''unified''', as the default cgroup mode in OpenRC since [[Release_Notes_for_Alpine_3.19.0#cgroups_v2|v3.19]].

To start {{ic|cgroups}} service:{{Cmd|# rc-service cgroups start}}
To enable cgroups and auto mount the cgroup filesystem on boot {{Cmd|# rc-update add cgroups}}

To enable ''hybrid'' cgroups, the previous default, edit the file {{Path|/etc/rc.conf}} and change the setting for {{ic|rc_cgroup_mode}} as follows:{{Cat|/etc/rc.conf|rc_cgroup_mode{{=}}"hybrid"}}

== Local service ==

Use the {{Path|/etc/local.d/}} directory to place programs or scripts which are to be run when the {{ic|local}} service is started or stopped.

If a file in this directory is executable and it has a .start extension, it will be run when the local service is started. If a file is executable and it has a .stop extension, it will be run when the local service is stopped. For more info refer [https://github.com/OpenRC/openrc/blob/master/local.d/README README]

To enable the {{ic|local}} service, issue the command:{{Cmd|# rc-update add local}}

== Preventing slow services from delaying system startup ==

Services that take a while to start will block the boot process until they complete. E.g.: {{ic|iwd}},{{ic|networking}},{{ic|chrony}} etc... might delay startup of an interactive system rather than start in the background.

=== Parallel services ===

If the setting {{Codeline|rc_parallel{{=}}"YES"}} is configured, the OpenRC system tries to start services in parallel for a slight speed improvement.
This setting however comes with a message from openRC developers:{{Warning|whilst we have improved parallel, it can still potentially lock the boot process. Don't file bugs about this.}}

=== Stacked runlevel method ===

Slow services can also be [https://ptrcnull.me/posts/openrc-async-services.html started after login prompt] using [[#Stacked runlevels|stacked runlevels]].
{{Warning|Editing the file {{Path|'''/etc/inittab'''}} wrongly will render the system unusable. Take backup and learn to restore it using rescue disk before proceeding.}}
# Create a custom runlevel '''async''': {{Cmd|# mkdir /etc/runlevels/async}}
# Add '''default''' as a stacked runlevel {{Cmd|# rc-update add -s default async}}
# Remove slow service from '''default''' runlevel and add them to the '''async''' runlevel: {{Cmd|# rc-update del <var>ServiceName</var> default}} {{Cmd|# rc-update add <var>ServiceName</var> async}}
# Enable the '''async''' runlevel by adding the line '''::once:/sbin/openrc async''' to {{Path|/etc/inittab}} file as follows: {{Cat|/etc/inittab|<nowiki>...
::wait:/sbin/openrc default
::once:/sbin/openrc async -q

# Set up a couple of getty's
tty1::respawn:/sbin/getty 38400 tty1
...</nowiki>}}
After rebooting, services from '''async''' will start separately. Other services started in '''default''' runlevel may still block [[TTY_Autologin|agetty]] from running, due to the {{ic|wait}} label.

== User services ==

OpenRC supports managing services for users. User services are available from [[Release_Notes_for_Alpine_3.22.0#OpenRC_User_services|v3.22]]. Here is the [https://pkgs.alpinelinux.org/contents?file=*&path=%2Fetc%2Fuser%2Finit.d&name=&branch=edge&repo=&arch=x86_64 list of OpenRC User services] available currently.

=== Config files and Runlevels for user services ===

OpenRC uses {{path|$XDG_CONFIG_HOME/rc}} for its user service configuration. If <code>$XDG_CONFIG_HOME</code> is unset, the fallback {{path|~/.config}} is used. The main configuration file for OpenRC User services is {{path|~/.config/rc/rc.conf}}.

The service scripts for each OpenRC user service provided as part of official packages can be found at {{Path|/etc/user/init.d/}} and their respective service configuration files at {{Path|/etc/user/conf.d/}}.

The folders {{path|~/.config/rc/init.d/}} and {{path|~/.config/rc/conf.d/}} can have user customized service scripts for User services and their respective configuration files. These scripts override official files at {{Path|/etc/user/}}, if their service names match.

Runlevels for user service are represented by directories in {{path|$XDG_CONFIG_HOME/rc/runlevels}}.

=== Prerequisites ===

* [[XDG_RUNTIME_DIR]] variable must be set

=== Configure environment variables ===

If you do not use a [[Display manager]] or if your login manager supports <code>~/.profile</code>, then it can be used to automatically start the user runlevel.

==== For Wayland ====
{{Tip|User services like {{pkg|wlsunset}} depend on the {{ic|$WAYLAND_DISPLAY}} environment variable. Hence, it is [https://gitlab.alpinelinux.org/alpine/aports/-/issues/17375#note_530383 recommended] to use '''gui''' runlevel for such services. Even though [[PipeWire]] can run at '''default''' runlevel, ensure that all your User services can run at the chosen runlevel.}}
* Allow propagation of the {{ic|$WAYLAND_DISPLAY}} and associated environment variables by adding the following lines to file {{path|~/.config/rc/rc.conf}} as follows:{{Cat|~/.config/rc/rc.conf|<nowiki>rc_env_allow="WAYLAND_DISPLAY"</nowiki>}}
* Create a custom '''gui''' user runlevel:{{Cmd|$ mkdir -p ~/.config/rc/runlevels/gui}}
* To start '''gui''' user runlevel, add the line {{ic|openrc -U gui}} to the startup file of your compositor. For eg, for [[Sway]] add:{{Cat|~/.config/sway/config|...
exec openrc -U gui}}

==== For Xorg ====

If [[Elogind]] is not used, ensure that [[Wayland#Creating_and_exporting_XDG_RUNTIME_DIR_manually|XDG_RUNTIME_DIR]] is set manually in {{path|~/.xinitrc}}. For eg, for [[dwm]] add:{{Cat|~/.xinitrc|<nowiki>...
if [ -z "$XDG_RUNTIME_DIR" ]; then
XDG_RUNTIME_DIR="/tmp/$(id -u)-runtime-dir"
mkdir -pm 0700 "$XDG_RUNTIME_DIR"
export XDG_RUNTIME_DIR
fi
openrc -U default
exec dwm</nowiki>}}

{{Note|For both the above cases, logout and login for the OpenRC user services to be started, before proceeding further.}}

=== User service management ===

Do not use '''doas''' when issuing User service commands. For managing user services, usual OpenRC commands can be used with '''-U''' option as distinct from the ''-u'' option.

Issue the command {{ic|$ rc-status -Ur}} to view and verify the current user runlevel as '''gui''' and '''default''' for Wayland and Xorg, respectively, before proceeding.

To start {{ic|ServiceName}} user service, issue the command:{{Cmd|$ rc-service -U <var>ServiceName</var> start}}
Verify that the above OpenRC user service is started before proceeding further: {{Cmd|$ rc-status -U}}
To enable {{ic|ServiceName}} user service, issue the command: {{Cmd|$ rc-update -U add <var>ServiceName</var>}}

{{Tip|Once a user service is configured, to prevent duplicate instance, remove them from {{Path|/etc/xdg/autostart}} folder or from the startup/config file.}}

=== PAM support ===

The default installation of OpenRC user services in Alpine Linux is without PAM support.

In scenarios where services should not be allowed to [https://wiki.gentoo.org/wiki/OpenRC#lingering linger] on logout, PAM support for OpenRC user services can be enabled by installing the {{pkg|openrc-user-pam}} package.{{Cmd|# apk add openrc-user-pam}}

== Troubleshooting ==

Whenever a openRC service fails to run, troubleshoot by enabling a debugging option, and then run the command.

For example, if running the command {{ic|rc-service <var>greetd</var> start}} causes the [[Greetd|greetd]] service to immediately crash, then alter the command to enable debug and to view its output:{{Cmd|# rc-service -d <var>greetd</var> restart}}

=== XDG_RUNTIME_DIR unset ===

While configuring [[#User services|user services]], running the command {{ic|$ doas rc-update add -U pipewire gui}} will generate the above error {{ic|XDG_RUNTIME_DIR unset}}. Always issue the command as normal user {{ic|$ rc-update add -U pipewire gui}} and do NOT use {{ic|doas}}.

=== ERROR: user.greetd failed to start ===

While using [[#User services|user services]] with [[greetd]], the above error message will appear. This failed error message for {{ic|user.greetd}} service is harmless as per {{MR|81612#note_492385}}.

=== failed to create display ===

When using openRC user services for {{ic|wlsunset}}, the following error message may appear:{{Cmd|daemon.err wlsunset: failed to create display}}You will need the GUI runlevel for services that depend on {{ic|$WAYLAND_DISPLAY}}. Refer [[#For Wayland| Configure environment variables For Wayland]] section.

== See also ==

* [[Writing Init Scripts]]
* [[Multiple Instances of Services]]
* [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user Guide]
* [https://github.com/OpenRC/openrc/blob/master/service-script-guide.md OpenRC Service Script Writing Guide]
* [https://wiki.gentoo.org/wiki/OpenRC Gentoo Wiki]
* [https://wiki.archlinux.org/title/OpenRC ArchWiki]
* [https://wiki.postmarketos.org/wiki/OpenRC PostmarketOS Wiki]
* [https://ptrcnull.me/posts/openrc-async-services.html Start services after login prompt]

[[Category:Booting]]
[[Category:System Administration]]
[[Category:Services]]

OpenRC

2026-04-01T18:59:57Z

Prabuanand: removed certain instructions. refer talk page for more information

Alpine Linux uses [https://github.com/OpenRC/ OpenRC] for its [https://en.wikipedia.org/wiki/Init init] system. The init system manages the services, including the boot and shutdown of your system. [[#User services|OpenRC User services]] can be used for managing services for users.

To learn the basics of OpenRC quickly, refer to the [https://docs.alpinelinux.org/user-handbook/0.1a/Working/openrc.html working with OpenRC] guide from the Alpine Linux documentation project.

== Quickstart ==

{|align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| width="50%" |Action
| |Command
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Managing a service - start,stop and restart'''
|-
| Start {{ic|ServiceName}} now || {{Cmd|# rc-service <var>ServiceName</var> start}}
|-
| Stop {{ic|ServiceName}} now || {{Cmd|# rc-service <var>ServiceName</var> stop}}
|-
| Restart {{ic|ServiceName}} now || {{Cmd|# rc-service <var>ServiceName</var> restart}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | '''Adding and removing service from runlevels'''
|-
| Add {{ic|ServiceName}} to {{ic|runlevel}} || {{Cmd|# rc-update add <var>ServiceName</var> <var>runlevel</var>}}
|-
| Remove {{ic|ServiceName}} from {{ic|runlevel}} || {{Cmd|# rc-update del <var>ServiceName</var> <var>runlevel</var>}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check services in a runlevel and their status'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To check status of {{ic|ServiceName}} || {{Cmd|$ rc-service <var>ServiceName</var> status}}
|-
| To view services configured at {{ic|runlevel}} || {{Cmd|$ rc-update show <var>runlevel</var>}}
|-
| To view currently active runlevels and state of services || {{Cmd|$ rc-status}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Check and manage runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view available runlevels || {{Cmd|$ rc-status -l}}
|-
| To change to a different {{ic|runlevel}} || {{Cmd|# openrc <var>runlevel</var>}}
|-
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" | ''' Stacked runlevels'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To add {{ic|s-runlevel}} as a stacked {{ic|runlevel}} || {{Cmd|# rc-update add -s <var>s-runlevel</var> <var>runlevel</var>}}
|-
| To remove {{ic|s-runlevel}} as a stacked {{ic|runlevel}} || {{Cmd|# rc-update del -s <var>s-runlevel</var> <var>runlevel</var>}}
|
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
| colspan="3" |'''User Services'''
|- style="background:#333333; color:#ffffff; font-size: 0.9em; text-align:center;"
|-
| To view currently active user runlevels and state of user services ({{ic|-U}}) || {{Cmd|$ rc-status -U}}
|-
| To change to a different user {{ic|runlevel}} || {{Cmd|$ openrc -U </var>runlevel</var>}}
|-
| Add user {{ic|ServiceName}} to user {{ic|runlevel}} || {{Cmd|$ rc-update -U add <var>ServiceName</var> <var>runlevel</var>}}
|-
| To add {{ic|s-runlevel}}as a stacked user {{ic|runlevel}} || {{Cmd|$ rc-update -U add -s <var>s-runlevel</var> <var>runlevel</var>}}
|}

== Runlevels ==

The [[BusyBox#init|BusyBox init]] executes [[OpenRC]] runlevel scripts according to entries in {{Path|/etc/inittab}}. A ''runlevel'' is basically a collection of services that needs to be started when certain conditions are met. Instead of using runlevel numbers, such as is used traditionally with ''SysV'' init, these are named, and users can create their own, if needed. The default startup uses the '''sysinit''', '''boot''', and '''default''' runlevels, in that order. Shutdown uses the '''shutdown''' runlevel.

The available runlevels are:
* '''default''' - Used if no runlevel is specified. (This is generally the runlevel you want to add services to.)
* '''hotplugged'''
* '''manual'''

The special runlevels are:

* '''sysinit''' - Brings up system specific stuff such as <code>/dev</code>, <code>/proc</code> and optionally <code>/sys</code> for Linux based systems. It also mounts <code>/lib/rc/init.d</code> as a ramdisk using tmpfs where available unless <code>/</code> is mounted rw at boot. <code>'''rc'''</code> uses <code>/lib/rc/init.d</code> to hold state information about the services it runs. '''sysinit''' always runs when the host first starts and should not be run again.
* '''boot''' - Generally, the only services that one should add to the '''boot''' runlevel are those which deal with the mounting of filesystems, setting the initial state of attached peripherals, and logging. Hotplugged services are added to the '''boot''' runlevel by the system. All services in the '''boot''' and '''sysinit''' runlevels are automatically included in all other runlevels except for those listed here.
* '''single''' - Stops all services except for those in the '''sysinit''' runlevel.
* '''reboot''' - Changes to the '''shutdown''' runlevel, and then reboots the host.
* '''shutdown''' - Changes to the shutdown '''runlevel''', and then halts the host.

=== Stacked runlevels ===

''Stacked'' runlevels allows for the "inheritance" of services. A few use cases are given below:-
* [https://docs.alpinelinux.org/user-handbook/0.1a/Working/openrc.html#_runlevel_stacking Running an office runlevel with VPN service]
* [[#Preventing slow services from delaying system startup|Preventing slow services from delaying system startup]]
For more detailed information, refer [https://wiki.gentoo.org/wiki/OpenRC/Stacked%20runlevel Gentoo wiki].

== Config files ==

The main configuration file for OpenRC is {{Path|/etc/rc.conf}}. The OpenRC service scripts for each service can be found at {{Path|/etc/init.d/}} and their respective service configuration files at {{Path|/etc/conf.d/}}.

== Command usage ==

OpenRC provides the following commands:
* {{ic|rc-update}}
* {{ic|rc-service}}
* {{ic|rc-status}}
* {{ic|openrc}}

To view the command usage for all OpenRC commands, use the '''--help''' or '''-h''' flag. For example: {{ic|$ rc-update '''--help'''}} or {{ic|$ rc-update '''-h'''}} will show usage information for {{ic|rc-update}}.

To {{ic|start}}, {{ic|stop}} or {{ic|restart}} a service {{ic|ServiceName}} immediately at the current runlevel:-
{{Cmd|$ doas rc-service <var>ServiceName</var> start}}
{{Cmd|$ doas rc-service <var>ServiceName</var> stop}}

To {{ic|add}} or {{ic|delete}} a service to/from the sequence of services that need to start automatically in future sessions at the {{ic|boot}} runlevel:
{{Cmd|$ doas rc-update add <var>ServiceName</var> boot}}
Note that the {{ic|'''default'''}} runlevel is assumed, so it does not need to be stated explicitly:
{{Cmd|$ doas rc-update add <var>ServiceName</var>}}
{{Cmd|$ doas rc-update del <var>ServiceName</var>}}

List the current status of all services; to display the status of all ''user services'' add '''-U''' :
{{Cmd|$ rc-status}}
List the assigned runlevels of all services; to display the runlevels of ''user services'' add '''-U''' :
{{Cmd|$ rc-update}}

Refer to the [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user guide] for more detailed information.

== Cgroups ==

Alpine Linux uses [https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html Cgroups version 2], or '''unified''', as the default cgroup mode in OpenRC since [[Release_Notes_for_Alpine_3.19.0#cgroups_v2|v3.19]].

To start {{ic|cgroups}} service:{{Cmd|# rc-service cgroups start}}
To enable cgroups and auto mount the cgroup filesystem on boot {{Cmd|# rc-update add cgroups}}

To enable ''hybrid'' cgroups, the previous default, edit the file {{Path|/etc/rc.conf}} and change the setting for {{ic|rc_cgroup_mode}} as follows:{{Cat|/etc/rc.conf|rc_cgroup_mode{{=}}"hybrid"}}

== Local service ==

Use the {{Path|/etc/local.d/}} directory to place programs or scripts which are to be run when the {{ic|local}} service is started or stopped.

If a file in this directory is executable and it has a .start extension, it will be run when the local service is started. If a file is executable and it has a .stop extension, it will be run when the local service is stopped. For more info refer [https://github.com/OpenRC/openrc/blob/master/local.d/README README]

To enable the {{ic|local}} service, issue the command:{{Cmd|# rc-update add local}}

== Preventing slow services from delaying system startup ==

Services that take a while to start will block the boot process until they complete. E.g.: {{ic|iwd}},{{ic|networking}},{{ic|chrony}} etc... might delay startup of an interactive system rather than start in the background.

=== Parallel services ===

If the setting {{Codeline|rc_parallel{{=}}"YES"}} is configured, the OpenRC system tries to start services in parallel for a slight speed improvement.
This setting however comes with a message from openRC developers:{{Warning|whilst we have improved parallel, it can still potentially lock the boot process. Don't file bugs about this.}}

=== Stacked runlevel method ===

Slow services can also be [https://ptrcnull.me/posts/openrc-async-services.html started after login prompt] using [[#Stacked runlevels|stacked runlevels]].
{{Warning|Editing the file {{Path|'''/etc/inittab'''}} wrongly will render the system unusable. Take backup and learn to restore it using rescue disk before proceeding.}}
# Create a custom runlevel '''async''': {{Cmd|# mkdir /etc/runlevels/async}}
# Add '''default''' as a stacked runlevel {{Cmd|# rc-update add -s default async}}
# Remove slow service from '''default''' runlevel and add them to the '''async''' runlevel: {{Cmd|# rc-update del <var>ServiceName</var> default}} {{Cmd|# rc-update add <var>ServiceName</var> async}}
# Enable the '''async''' runlevel by adding the line '''::once:/sbin/openrc async''' to {{Path|/etc/inittab}} file as follows: {{Cat|/etc/inittab|<nowiki>...
::wait:/sbin/openrc default
::once:/sbin/openrc async -q

# Set up a couple of getty's
tty1::respawn:/sbin/getty 38400 tty1
...</nowiki>}}
After rebooting, services from '''async''' will start separately. Other services started in '''default''' runlevel may still block [[TTY_Autologin|agetty]] from running, due to the {{ic|wait}} label.

== User services ==

OpenRC supports managing services for users. User services are available from [[Release_Notes_for_Alpine_3.22.0#OpenRC_User_services|v3.22]]. Here is the [https://pkgs.alpinelinux.org/contents?file=*&path=%2Fetc%2Fuser%2Finit.d&name=&branch=edge&repo=&arch=x86_64 list of OpenRC User services] available currently.

Do not use '''doas''' when using user service commands. For managing user services, usual OpenRC commands can be used with '''-U''' option as distinct from the ''-u'' option.

=== Config files and Runlevels for user services ===

OpenRC uses {{path|$XDG_CONFIG_HOME/rc}} for its user service configuration. If <code>$XDG_CONFIG_HOME</code> is unset, the fallback {{path|~/.config}} is used. The main configuration file for OpenRC User services is {{path|~/.config/rc/rc.conf}}.

The service scripts for each OpenRC user service provided as part of official packages can be found at {{Path|/etc/user/init.d/}} and their respective service configuration files at {{Path|/etc/user/conf.d/}}.

The folders {{path|~/.config/rc/init.d/}} and {{path|~/.config/rc/conf.d/}} can have user customized service scripts for User services and their respective configuration files. These scripts override official files at {{Path|/etc/user/}}, if their service names match.

Runlevels for user service are represented by directories in {{path|$XDG_CONFIG_HOME/rc/runlevels}}.

=== Prerequisites ===

* [[XDG_RUNTIME_DIR]] variable must be set

=== Configure environment variables ===

If you do not use a [[Display manager]] or if your login manager supports <code>~/.profile</code>, then it can be used to automatically start the user runlevel.

==== For Wayland ====
{{Tip|User services like {{pkg|wlsunset}} depend on the {{ic|$WAYLAND_DISPLAY}} environment variable. Hence, it is [https://gitlab.alpinelinux.org/alpine/aports/-/issues/17375#note_530383 recommended] to use '''gui''' runlevel for such services. Even though [[PipeWire]] can run at '''default''' runlevel, ensure that all your User services can run at the chosen runlevel.}}
* Allow propagation of the {{ic|$WAYLAND_DISPLAY}} and associated environment variables by adding the following lines to file {{path|~/.config/rc/rc.conf}} as follows:{{Cat|~/.config/rc/rc.conf|<nowiki>rc_env_allow="WAYLAND_DISPLAY"</nowiki>}}
* Create a custom '''gui''' user runlevel:{{Cmd|$ mkdir -p ~/.config/rc/runlevels/gui}}
* To start '''gui''' user runlevel, add the line {{ic|openrc -U gui}} to the startup file of your compositor. For eg, for [[Sway]] add:{{Cat|~/.config/sway/config|...
exec openrc -U gui}}

==== For Xorg ====

If [[Elogind]] is not used, ensure that [[Wayland#Creating_and_exporting_XDG_RUNTIME_DIR_manually|XDG_RUNTIME_DIR]] is set manually in {{path|~/.xinitrc}}. For eg, for [[dwm]] add:{{Cat|~/.xinitrc|<nowiki>...
if [ -z "$XDG_RUNTIME_DIR" ]; then
XDG_RUNTIME_DIR="/tmp/$(id -u)-runtime-dir"
mkdir -pm 0700 "$XDG_RUNTIME_DIR"
export XDG_RUNTIME_DIR
fi
openrc -U default
exec dwm</nowiki>}}

{{Note|For both the above cases, logout and login for the OpenRC user services to be started, before proceeding further.}}

=== User service management ===

Issue the command {{ic|$ rc-status -Ur}} to view and verify the current user runlevel as '''gui''' and '''default''' for Wayland and Xorg, respectively, before proceeding.

To start {{ic|ServiceName}} user service, issue the command:{{Cmd|$ rc-service -U <var>ServiceName</var> start}}
Verify that the above OpenRC user service is started before proceeding further: {{Cmd|$ rc-status -U}}
To enable {{ic|ServiceName}} user service, issue the command: {{Cmd|$ rc-update -U add <var>ServiceName</var>}}

{{Tip|Once a user service is configured, to prevent duplicate instance, remove them from {{Path|/etc/xdg/autostart}} folder or from the startup/config file.}}

=== PAM support ===

The default installation of OpenRC user services in Alpine Linux is without PAM support.

In scenarios where services should not be allowed to [https://wiki.gentoo.org/wiki/OpenRC#lingering linger] on logout, PAM support for OpenRC user services can be enabled by installing the {{pkg|openrc-user-pam}} package.{{Cmd|# apk add openrc-user-pam}}

== Troubleshooting ==

Whenever a openRC service fails to run, troubleshoot by enabling a debugging option, and then run the command.

For example, if running the command {{ic|rc-service <var>greetd</var> start}} causes the [[Greetd|greetd]] service to immediately crash, then alter the command to enable debug and to view its output:{{Cmd|# rc-service -d <var>greetd</var> restart}}

=== XDG_RUNTIME_DIR unset ===

While configuring [[#User services|user services]], running the command {{ic|$ doas rc-update add -U pipewire gui}} will generate the above error {{ic|XDG_RUNTIME_DIR unset}}. Always issue the command as normal user {{ic|$ rc-update add -U pipewire gui}} and do NOT use {{ic|doas}}.

=== ERROR: user.greetd failed to start ===

While using [[#User services|user services]] with [[greetd]], the above error message will appear. This failed error message for {{ic|user.greetd}} service is harmless as per {{MR|81612#note_492385}}.

=== failed to create display ===

When using openRC user services for {{ic|wlsunset}}, the following error message may appear:{{Cmd|daemon.err wlsunset: failed to create display}}You will need the GUI runlevel for services that depend on {{ic|$WAYLAND_DISPLAY}}. Refer [[#For Wayland| Configure environment variables For Wayland]] section.

== See also ==

* [[Writing Init Scripts]]
* [[Multiple Instances of Services]]
* [https://github.com/OpenRC/openrc/blob/master/user-guide.md OpenRC user Guide]
* [https://github.com/OpenRC/openrc/blob/master/service-script-guide.md OpenRC Service Script Writing Guide]
* [https://wiki.gentoo.org/wiki/OpenRC Gentoo Wiki]
* [https://wiki.archlinux.org/title/OpenRC ArchWiki]
* [https://wiki.postmarketos.org/wiki/OpenRC PostmarketOS Wiki]
* [https://ptrcnull.me/posts/openrc-async-services.html Start services after login prompt]

[[Category:Booting]]
[[Category:System Administration]]
[[Category:Services]]

System Disk Mode

2026-03-26T06:27:54Z

Prabuanand: made minor rewording, added a tip and clarified on the internet access

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This mode is suitable for use cases like [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

{{Tip|If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux.}}

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

The [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] script performs a traditional hard disk install of your running system and can be customized using [[Alpine_setup_scripts#Environment_Variables|environment variables]]. A working [[Configure_Networking#Connectivity_testing|internet access]] configured in step 1 below is mandatory to complete this installation, if '''Extended image''' is not used. The detailed steps are given below:

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# The above command detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the optional [[Alpine_setup_scripts#Environment_Variables|environment variable]] <Code>BOOTLOADER</Code> and completes the installation by transferring your running system's configuration to the hard disk.
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

==== Check File System Kernel Modules are Loading ====

Run the below command to output the File System Kernel modules, where the file system can be one among the following: '''ext2''', '''ext3''', '''ext4''', '''btrfs''', '''xfs''', '''fat''':

{{Cmd|<nowiki># lsmod | grep <File System></nowiki>}}

An example output is given below for the above command, with necessary abbreviations explained:

<Pre>
alpinepc:~# lsmod | grep ext4

ext4 1155072 2
crc16 12288 1 ext4
mbcache 16384 1 ext4
jbd2 200704 1 ext4
</Pre>
EXT4 = [[Filesystems|File System]] 
CRC16 = EXT4 Compression Support 
MBCACHE = MetaData Cache 
JBD2 = Journaling 

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

Talk:Riscv64

2026-03-26T04:49:03Z

Prabuanand: reminder about category section

== Can we move to host implementation targeted sub-pages? ==
There's a lot of information here regarding QEMU based installation which is fantastic for getting off the ground. There are a lot of specifics regarding different RISCV64 processors and boards though. This page could quickly get muddied with information for SiFive, Allwinner, SpacemiT, etc. My thought is that the current contents of this page become sub-page and the main Riscv64 page reference the different types of installation targets.
: Sure! I can see that this page is already long enough with just the QEMU content, so I’m happy to see it separated into its own page, as long as we can leave a “breadcrumb” from this main [[Riscv64]] page to the new one. Thanks! [[User:Fission|Fission]] ([[User talk:Fission|talk]]) 21:30, 25 March 2026 (UTC)
:: Very happy to see content coming in [[Riscv64]] page. For all content pages, remember to add the Riscv64 to the category section. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 04:49, 26 March 2026 (UTC)

Setting up disks manually

2026-03-26T04:44:07Z

Prabuanand: added Troubleshooting link

Setting up disks manually involves creating or modifying partitions using partitioning tools and formatting them using various filesystem utilities to allow [[System Disk Mode]] or traditional HDD Installation of Alpine Linux at the end of [[Installation#Base configuration|base configuration step]] of installation. In addition to the above information, this page also documents various Disk layouts involving RAID, Encryption and LVM.

{{Tip|The default [[Installation#setup-alpine based System Disk Install|System Disk]] installation requires and uses an entire HDD. If you intend to install Alpine Linux on a specific partition follow the [[System Disk Mode#setup-disk based Installation|setup-disk based installation page]].}}

== Manual partitioning ==

Creating partitions manually requires partitioning tool packages and formatting them requires appropriate filesystem utilities. Due to the minimal nature of Alpine Linux, the installation image environment may have only limited options. Depending on your requirements, install the necessary packages at the end of [[Installation#Base configuration|base configuration step]] of installation before proceeding further.

{{Note|Some of the tools mentioned on this page may require working [[Configure_Networking#Connectivity_testing|Internet access]].}}

* Create a partition using the available [[#Partitioning tools|Partitioning tools]]
* If MBR partition table is used, some partitioning tool may require manual steps to set up bootable flag.
* Once the necessary partition(s) have been created, do a reboot before proceeding further.
* [[#Formatting partitions|Format the partition]] using the appropriate tool based on the filesystem used. Some partition tools may format the partitions automatically.

== Partitioning tools ==

Only the basic busybox built-in <code>fdisk</code> command available by default along with <code>sfdisk</code>. Install any of the below listed partitioning tools immediately after setting up [[Installation#Base_configuration|base configuration]].

{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| width="10%" |Command
|width="15%" | Package name
|width="40%"| Features
| | Limitations
|-
| fdisk || Inbuilt {{pkg|busybox}} || can read GPT, Modify MBR || Cannot modify GPT
|-
| gdisk || {{pkg|gptfdisk}} || text mode, supports MBR/GPT bidirectional conversion, best for managing GPT partition tables|| None
|-
| cgdisk || {{pkg|gptfdisk}} || menu driven curses interface for gdisk || None
|-
| sgdisk || {{pkg|sgdisk}} || scriptable gdisk || Non-interactive
|-
| fdisk || {{pkg|util-linux-misc}} || text mode, supports both gpt and MBR, best for managing MBR partition tables || None except size due to other tools
|-
| cfdisk || {{pkg|cfdisk}} || menu driven curses interface for fdisk || None
|-
| sfdisk || {{pkg|sfdisk}} || scriptable fdisk || Non-interactive
|-
| parted || {{pkg|parted}} || text mode, supports both gpt and MBR|| cannot convert MBR to GPT, different interface from above tools
|}

Graphical tools like {{pkg|gparted}} and {{pkg|gnome-disk-utility}} can be used only after [[Installation#Post-Installation|setting up a graphical environment]].

== Creating partitions ==

For Alpine Linux, only the '''(/)'''root partition is mandatory. Even a '''/boot''' partition and '''swap''' are optional.

{{Warning|Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.}}
{{ic|cfdisk}} will be used in all examples here as it is based on text menu without any dependencies. However, installing the {{Pkg|cfdisk}} package requires network to be available if using Standard ISO boot image. Alternately, {{Pkg|<code>sfdisk</code>}} can be installed without network.

{{Tip|Use {{ic|cgdisk}} from {{Pkg|gptfdisk}} package for GPT partitions and for conversion from MBR to GPT.}}

The following step installs the {{Pkg|cfdisk}} package: {{cmd|# apk add cfdisk }}

Before using {{ic|cfdisk}} to create partitions, the disk name must be identified by using {{ic|blkid}}:{{cmd|# blkid}}
<pre>
/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"
</pre>

When {{ic|cfdisk}} is run as follows, it looks for existing partitions on the disk {{Path|/dev/sdX}}: {{cmd|# cfdisk /dev/sdX}}

== Resizing an existing partition ==
{{Warning|Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.}}

{{ic|cfdisk}} and {{ic|resize2fs}} from {{pkg|e2fsprogs-extra}} package can be used to resize existing partitions of ext2/3/4 filsystem on the disk. For other filsystems, the necessary [[Filesystems#Filesystem_Tools|filesystem tools]] must be installed. This can be done while booted.

[[File:Cfdisk screenshot alpine 2024-03-04 143916.png|thumb|cfdisk screenshot ]]

To resize disk, launch the {{ic|cfdisk}}: {{cmd|# cfdisk {{path|/dev/sda}}}}

# Select the target partition, here as per image {{path|/dev/sda3}}
# Select ''Resize'' from the bottom menu.
# Enter the new ''Size'' at the prompt.
# Select ''Write'', then ''Quit''

If a filesystem is resized with -f (online mode), then the system must be rebooted immediately after the change is made.

{{cmd|# resize2fs -f {{path|/dev/sda3}}
&num; reboot}}

== Formatting partitions ==

{{Warning|The {{Path|/dev/sdXY}} is only an example. Make sure you use the right partition name/number. Use {{ic|blkid}} command to verify the partition name/number. Choosing the wrong partition leads to data loss. If you are unsure, do not proceed, seek [[Alpine Linux:Support|support]].}}

Whenever a partition is [[#Creating_partitions|created]], the partition must be formatted first before using it. Depending on the filesystem to be used, the necessary [[Filesystems#Filesystem_Tools|formatting tool]] for the filesystem must be installed first.
{{:Filesystems}}

Install the [[Filesystems#Filesystem_Tools|filesystem tools]] first, if not done already. The following examples show how to use the formatting tools for different filesystems:

* e2fsprogs for ext4,ext3 and ext2. ext4 is the default filesystem in Alpine Linux: {{Cmd|# mkfs.ext4 /dev/sdaXY}}
* btrfs-progs for [[btrfs]] filesystem. {{Cmd|# mkfs.btrfs /dev/sdaXY}}
* dosfstools for fat12/fat16/fat32 filesystem. This is also used for [[UEFI|EFI]] system partition(ESP). {{Cmd|# mkfs.vfat /dev/sdaXY}}
* f2fs-tools for [[F2FS]] filesystem. {{Cmd|# mkfs.f2fs /dev/sdaXY}}

== Disk layouts ==

It is possible to have one or more of [[#RAID|RAID]], [[#Encryption|encrypted]], and/or [[#LVM|Logical Volume]] on your {{Path|/}} (root) volume. However, the Alpine init script only knows how to handle them when they're layered in that order, and your initram and extlinux.conf files in the {{Path|/boot}} partition are configured properly.

Your {{Path|/boot}} directory cannot reside on an encrypted or LVM volume, at least not with Alpine's default bootloader (extlinux). (Grub2 can deal with {{Path|/boot}} being on an LVM volume.) The usual practice is to create a small partition for {{Path|/boot}}, then devote the rest of your disk to a separate partition on which you layer one or more of RAID, encryption, and/or Logical Volumes.

Sometimes {{Path|/boot}} is also set up as a mirrored (RAID1) volume. However, this is just for post-init access. That way, when you write a new kernel or bootloader config file to {{Path|/boot}}, it gets written to multiple physical partitions. During the pre-init, bootloader phase, only one of those partitions will be read from.

A typical setup might look like this:

<pre>
One-disk system
---------------
+------------------------------------------------+
| small partition (32--100M), holding |
| only /boot, filesystem needn't be journaled |
+------------------------------------------------+
| rest of disk in second partition |
| +------------------------------------------+ |
| | cryptsetup volume | |
| | +-------------------------------------+ | |
| | | LVM PV, containing single VG, | | |
| | | containing multiple LVs, holding | | |
| | | /, /home, swap, etc | | |
| | +-------------------------------------+ | |
| +------------------------------------------+ |
+------------------------------------------------+

Two-disk system
---------------
+------------------------------------------------+ +------------------------------------------------+
| small partition (32--100M), holding | | small partition (32--100M), holding | These 2 partitions might
| only /boot, filesystem needn't be journaled | | only /boot, filesystem needn't be journaled | form a mirrored (RAID1)
+------------------------------------------------+ +------------------------------------------------+ volume
| rest of disk in second partition | | rest of disk in second partition |
| T================================================================================================T | These 2 partitions form
| T +--------------------------------------------------------------------------------------------+ T | a second mirrored
| T | cryptsetup volume | T | (RAID1) volume
| T | +---------------------------------------------------------------------------------------+ | T |
| T | | LVM PV, containing single VG, | | T |
| T | | containing multiple LVs, holding | | T |
| T | | /, /home, swap, etc | | T |
| T | +---------------------------------------------------------------------------------------+ | T |
| T +--------------------------------------------------------------------------------------------+ T |
| T================================================================================================T |
| | | |
+------------------------------------------------+ +------------------------------------------------+

</pre>

In a three-disk system, the {{Path|/boot}} would still be RAID1, but the larger partition might, in that case, be RAID5.

=== RAID ===
{{Main|Setting up a software RAID array}}
<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device.

If you want to build your RAID array manually, see [[Setting up a software RAID array]]. Then you can add additional layers of encryption and/or Logical Volumes, or just assemble the RAID array, and supply the {{Path|/dev/mdi}} device directly to [[setup-disk]]. When you're finished, be sure to disassemble the RAID array before rebooting.

If <code>setup-disk</code> sees that you're using RAID, either because you gave it the <code>-r</code> switch, or multiple devices, or a {{Path|/dev/mdi}} device, then it will set up your initramfs and extlinux.conf file properly. However, in other cases, such as when you're also using encryption, or you invoke <code>setup-disk</code> with a mounted directory argument, these might not be properly set up for RAID. In that case, you may need to manually edit/rebuild them. The following assumes that <code>$MNT</code> holds the root directory you're installing into:

{{Cmd|1=echo "/sbin/mdadm" > $MNT/etc/mkinitfs/files.d/raid
echo "/etc/mdadm.conf" >> $MNT/etc/mkinitfs/files.d/raid
# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..."
# includes raid (this field is space-separated and quoted)
mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT
# edit $MNT/etc/update-extlinux.conf to make sure modules=... contains
# raid1 or raid456 (whichever your / is on; this field is comma-separated)
# also check the root= setting
extlinux --raid --install $MNT/boot --update
}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}. And you might need to copy {{Path|/usr/share/syslinux/mbr.bin}} to your disk's MBR.

=== Encryption ===
{{Main|Setting up encrypted volumes with LUKS}}

You can add an additional Logical Volume layer, or just unlock the volume you've created (using <code>cryptsetup luksOpen ...</code>), and supply the {{Path|/dev/mapper/something}} device directly to [[setup-disk]]. When you're finished, be sure to relock the volume (using <code>cryptsetup luksClose ...</code>) before rebooting.

If you install your {{Path|/}} (root) on an encrypted volume, you'll need to manually edit/rebuild your initram and your extlinux.conf file. The following assumes that <code>$MNT</code> holds the root directory you're installing into, that you've created the cryptvolume on the device {{Path|/dev/md2}}, and that you want to unlock the encrypted volume into a virtual volume named "crypt":

{{Cmd|1=# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..."
# includes cryptsetup (this field is space-separated and quoted)
mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT
# edit $MNT/etc/update-extlinux.conf to make sure default_kernel_opts="..."
# contains cryptroot=/dev/md1 and cryptdm=crypt (this field is also space-separated and quoted)
# also check the root= setting
extlinux --install $MNT/boot --update
}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}.

=== LVM ===
{{Main|Setting up Logical Volumes with LVM}}

<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch.

If you instead want to build your LVM system manually, see [[Setting up Logical Volumes with LVM]]. Then <code>vgchange -ay</code>, format and mount your volumes, and supply the root mountpoint to [[setup-disk]]. When you're finished, be sure to
{{Cmd|umount ...
vgchange -an}}
before rebooting.

If <code>setup-disk</code> sees that you're using LVM, perhaps because you gave it the <code>-L</code> switch, then it will set up your initram and extlinux.conf file properly. However, in other cases, these might not be properly set up. In that case, you may need to manually edit/rebuild them. The following assumes that <code>$MNT</code> holds the root directory you're installing into:

{{Cmd|1=# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..."
# includes lvm (this field is space-separated and quoted)
mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT
# edit $MNT/etc/update-extlinux.conf to make sure root= is set correctly
extlinux --install $MNT/boot --update
}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}.

== Troubleshooting ==

Refer to [[System_Disk_Mode#Troubleshooting|Troubleshooting]] page as most issues documented here earlier have been consolidated on that page.

== See also ==

* [https://www.rodsbooks.com/gdisk/index.html Gdisk official website] '' walkthroughs available for gdisk,cgdisk and sgdisk''
[[Category:Storage]]

Setting up disks manually

2026-03-26T04:41:14Z

Prabuanand: cleaned up the introduction and added steps for Manual partitioning with a Note and Tip

Setting up disks manually involves creating or modifying partitions using partitioning tools and formatting them using various filesystem utilities to allow [[System Disk Mode]] or traditional HDD Installation of Alpine Linux at the end of [[Installation#Base configuration|base configuration step]] of installation. In addition to the above information, this page also documents various Disk layouts involving RAID, Encryption and LVM.

{{Tip|The default [[Installation#setup-alpine based System Disk Install|System Disk]] installation requires and uses an entire HDD. If you intend to install Alpine Linux on a specific partition follow the [[System Disk Mode#setup-disk based Installation|setup-disk based installation page]].}}

== Manual partitioning ==

Creating partitions manually requires partitioning tool packages and formatting them requires appropriate filesystem utilities. Due to the minimal nature of Alpine Linux, the installation image environment may have only limited options. Depending on your requirements, install the necessary packages at the end of [[Installation#Base configuration|base configuration step]] of installation before proceeding further.

{{Note|Some of the tools mentioned on this page may require working [[Configure_Networking#Connectivity_testing|Internet access]].}}

* Create a partition using the available [[#Partitioning tools|Partitioning tools]]
* If MBR partition table is used, some partitioning tool may require manual steps to set up bootable flag.
* Once the necessary partition(s) have been created, do a reboot before proceeding further.
* [[#Formatting partitions|Format the partition]] using the appropriate tool based on the filesystem used. Some partition tools may format the partitions automatically.

== Partitioning tools ==

Only the basic busybox built-in <code>fdisk</code> command available by default along with <code>sfdisk</code>. Install any of the below listed partitioning tools immediately after setting up [[Installation#Base_configuration|base configuration]].

{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| width="10%" |Command
|width="15%" | Package name
|width="40%"| Features
| | Limitations
|-
| fdisk || Inbuilt {{pkg|busybox}} || can read GPT, Modify MBR || Cannot modify GPT
|-
| gdisk || {{pkg|gptfdisk}} || text mode, supports MBR/GPT bidirectional conversion, best for managing GPT partition tables|| None
|-
| cgdisk || {{pkg|gptfdisk}} || menu driven curses interface for gdisk || None
|-
| sgdisk || {{pkg|sgdisk}} || scriptable gdisk || Non-interactive
|-
| fdisk || {{pkg|util-linux-misc}} || text mode, supports both gpt and MBR, best for managing MBR partition tables || None except size due to other tools
|-
| cfdisk || {{pkg|cfdisk}} || menu driven curses interface for fdisk || None
|-
| sfdisk || {{pkg|sfdisk}} || scriptable fdisk || Non-interactive
|-
| parted || {{pkg|parted}} || text mode, supports both gpt and MBR|| cannot convert MBR to GPT, different interface from above tools
|}

Graphical tools like {{pkg|gparted}} and {{pkg|gnome-disk-utility}} can be used only after [[Installation#Post-Installation|setting up a graphical environment]].

== Creating partitions ==

For Alpine Linux, only the '''(/)'''root partition is mandatory. Even a '''/boot''' partition and '''swap''' are optional.

{{Warning|Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.}}
{{ic|cfdisk}} will be used in all examples here as it is based on text menu without any dependencies. However, installing the {{Pkg|cfdisk}} package requires network to be available if using Standard ISO boot image. Alternately, {{Pkg|<code>sfdisk</code>}} can be installed without network.

{{Tip|Use {{ic|cgdisk}} from {{Pkg|gptfdisk}} package for GPT partitions and for conversion from MBR to GPT.}}

The following step installs the {{Pkg|cfdisk}} package: {{cmd|# apk add cfdisk }}

Before using {{ic|cfdisk}} to create partitions, the disk name must be identified by using {{ic|blkid}}:{{cmd|# blkid}}
<pre>
/dev/sdX1: LABEL="some" UUID="..." TYPE="vfat"
/dev/sdX2: LABEL="other" UUID="..." TYPE="ext4"
</pre>

When {{ic|cfdisk}} is run as follows, it looks for existing partitions on the disk {{Path|/dev/sdX}}: {{cmd|# cfdisk /dev/sdX}}

== Resizing an existing partition ==
{{Warning|Make sure to choose the correct disk device in the below section. If you choose the wrong device, you will lose your data. Make a backup first and do not proceed, if you are unsure.}}

{{ic|cfdisk}} and {{ic|resize2fs}} from {{pkg|e2fsprogs-extra}} package can be used to resize existing partitions of ext2/3/4 filsystem on the disk. For other filsystems, the necessary [[Filesystems#Filesystem_Tools|filesystem tools]] must be installed. This can be done while booted.

[[File:Cfdisk screenshot alpine 2024-03-04 143916.png|thumb|cfdisk screenshot ]]

To resize disk, launch the {{ic|cfdisk}}: {{cmd|# cfdisk {{path|/dev/sda}}}}

# Select the target partition, here as per image {{path|/dev/sda3}}
# Select ''Resize'' from the bottom menu.
# Enter the new ''Size'' at the prompt.
# Select ''Write'', then ''Quit''

If a filesystem is resized with -f (online mode), then the system must be rebooted immediately after the change is made.

{{cmd|# resize2fs -f {{path|/dev/sda3}}
&num; reboot}}

== Formatting partitions ==

{{Warning|The {{Path|/dev/sdXY}} is only an example. Make sure you use the right partition name/number. Use {{ic|blkid}} command to verify the partition name/number. Choosing the wrong partition leads to data loss. If you are unsure, do not proceed, seek [[Alpine Linux:Support|support]].}}

Whenever a partition is [[#Creating_partitions|created]], the partition must be formatted first before using it. Depending on the filesystem to be used, the necessary [[Filesystems#Filesystem_Tools|formatting tool]] for the filesystem must be installed first.
{{:Filesystems}}

Install the [[Filesystems#Filesystem_Tools|filesystem tools]] first, if not done already. The following examples show how to use the formatting tools for different filesystems:

* e2fsprogs for ext4,ext3 and ext2. ext4 is the default filesystem in Alpine Linux: {{Cmd|# mkfs.ext4 /dev/sdaXY}}
* btrfs-progs for [[btrfs]] filesystem. {{Cmd|# mkfs.btrfs /dev/sdaXY}}
* dosfstools for fat12/fat16/fat32 filesystem. This is also used for [[UEFI|EFI]] system partition(ESP). {{Cmd|# mkfs.vfat /dev/sdaXY}}
* f2fs-tools for [[F2FS]] filesystem. {{Cmd|# mkfs.f2fs /dev/sdaXY}}

== Disk layouts ==

It is possible to have one or more of [[#RAID|RAID]], [[#Encryption|encrypted]], and/or [[#LVM|Logical Volume]] on your {{Path|/}} (root) volume. However, the Alpine init script only knows how to handle them when they're layered in that order, and your initram and extlinux.conf files in the {{Path|/boot}} partition are configured properly.

Your {{Path|/boot}} directory cannot reside on an encrypted or LVM volume, at least not with Alpine's default bootloader (extlinux). (Grub2 can deal with {{Path|/boot}} being on an LVM volume.) The usual practice is to create a small partition for {{Path|/boot}}, then devote the rest of your disk to a separate partition on which you layer one or more of RAID, encryption, and/or Logical Volumes.

Sometimes {{Path|/boot}} is also set up as a mirrored (RAID1) volume. However, this is just for post-init access. That way, when you write a new kernel or bootloader config file to {{Path|/boot}}, it gets written to multiple physical partitions. During the pre-init, bootloader phase, only one of those partitions will be read from.

A typical setup might look like this:

<pre>
One-disk system
---------------
+------------------------------------------------+
| small partition (32--100M), holding |
| only /boot, filesystem needn't be journaled |
+------------------------------------------------+
| rest of disk in second partition |
| +------------------------------------------+ |
| | cryptsetup volume | |
| | +-------------------------------------+ | |
| | | LVM PV, containing single VG, | | |
| | | containing multiple LVs, holding | | |
| | | /, /home, swap, etc | | |
| | +-------------------------------------+ | |
| +------------------------------------------+ |
+------------------------------------------------+

Two-disk system
---------------
+------------------------------------------------+ +------------------------------------------------+
| small partition (32--100M), holding | | small partition (32--100M), holding | These 2 partitions might
| only /boot, filesystem needn't be journaled | | only /boot, filesystem needn't be journaled | form a mirrored (RAID1)
+------------------------------------------------+ +------------------------------------------------+ volume
| rest of disk in second partition | | rest of disk in second partition |
| T================================================================================================T | These 2 partitions form
| T +--------------------------------------------------------------------------------------------+ T | a second mirrored
| T | cryptsetup volume | T | (RAID1) volume
| T | +---------------------------------------------------------------------------------------+ | T |
| T | | LVM PV, containing single VG, | | T |
| T | | containing multiple LVs, holding | | T |
| T | | /, /home, swap, etc | | T |
| T | +---------------------------------------------------------------------------------------+ | T |
| T +--------------------------------------------------------------------------------------------+ T |
| T================================================================================================T |
| | | |
+------------------------------------------------+ +------------------------------------------------+

</pre>

In a three-disk system, the {{Path|/boot}} would still be RAID1, but the larger partition might, in that case, be RAID5.

=== RAID ===
{{Main|Setting up a software RAID array}}
<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device.

If you want to build your RAID array manually, see [[Setting up a software RAID array]]. Then you can add additional layers of encryption and/or Logical Volumes, or just assemble the RAID array, and supply the {{Path|/dev/mdi}} device directly to [[setup-disk]]. When you're finished, be sure to disassemble the RAID array before rebooting.

If <code>setup-disk</code> sees that you're using RAID, either because you gave it the <code>-r</code> switch, or multiple devices, or a {{Path|/dev/mdi}} device, then it will set up your initramfs and extlinux.conf file properly. However, in other cases, such as when you're also using encryption, or you invoke <code>setup-disk</code> with a mounted directory argument, these might not be properly set up for RAID. In that case, you may need to manually edit/rebuild them. The following assumes that <code>$MNT</code> holds the root directory you're installing into:

{{Cmd|1=echo "/sbin/mdadm" > $MNT/etc/mkinitfs/files.d/raid
echo "/etc/mdadm.conf" >> $MNT/etc/mkinitfs/files.d/raid
# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..."
# includes raid (this field is space-separated and quoted)
mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT
# edit $MNT/etc/update-extlinux.conf to make sure modules=... contains
# raid1 or raid456 (whichever your / is on; this field is comma-separated)
# also check the root= setting
extlinux --raid --install $MNT/boot --update
}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}. And you might need to copy {{Path|/usr/share/syslinux/mbr.bin}} to your disk's MBR.

=== Encryption ===
{{Main|Setting up encrypted volumes with LUKS}}

You can add an additional Logical Volume layer, or just unlock the volume you've created (using <code>cryptsetup luksOpen ...</code>), and supply the {{Path|/dev/mapper/something}} device directly to [[setup-disk]]. When you're finished, be sure to relock the volume (using <code>cryptsetup luksClose ...</code>) before rebooting.

If you install your {{Path|/}} (root) on an encrypted volume, you'll need to manually edit/rebuild your initram and your extlinux.conf file. The following assumes that <code>$MNT</code> holds the root directory you're installing into, that you've created the cryptvolume on the device {{Path|/dev/md2}}, and that you want to unlock the encrypted volume into a virtual volume named "crypt":

{{Cmd|1=# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..."
# includes cryptsetup (this field is space-separated and quoted)
mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT
# edit $MNT/etc/update-extlinux.conf to make sure default_kernel_opts="..."
# contains cryptroot=/dev/md1 and cryptdm=crypt (this field is also space-separated and quoted)
# also check the root= setting
extlinux --install $MNT/boot --update
}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}.

=== LVM ===
{{Main|Setting up Logical Volumes with LVM}}

<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch.

If you instead want to build your LVM system manually, see [[Setting up Logical Volumes with LVM]]. Then <code>vgchange -ay</code>, format and mount your volumes, and supply the root mountpoint to [[setup-disk]]. When you're finished, be sure to
{{Cmd|umount ...
vgchange -an}}
before rebooting.

If <code>setup-disk</code> sees that you're using LVM, perhaps because you gave it the <code>-L</code> switch, then it will set up your initram and extlinux.conf file properly. However, in other cases, these might not be properly set up. In that case, you may need to manually edit/rebuild them. The following assumes that <code>$MNT</code> holds the root directory you're installing into:

{{Cmd|1=# edit $MNT/etc/mkinitfs/mkinitfs.conf to make sure features="..."
# includes lvm (this field is space-separated and quoted)
mkinitfs -c $MNT/etc/mkinitfs/mkinitfs.conf -b $MNT
# edit $MNT/etc/update-extlinux.conf to make sure root= is set correctly
extlinux --install $MNT/boot --update
}}

You might also need to manually tweak {{Path|$MNT/etc/fstab}}.

== Troubleshooting ==

== See also ==
* [https://www.rodsbooks.com/gdisk/index.html Gdisk official website] '' walkthroughs available for gdisk,cgdisk and sgdisk''
[[Category:Storage]]

Talk:OpenRC

2026-03-24T16:46:15Z

Prabuanand: /* User Services -> Runlevels */

The [https://wiki.alpinelinux.org/wiki/OpenRC#Preventing_slow_services_from_delaying_boot Preventing slow services from delaying boot] passage currently uses '''chronyd''' as an example of a service that may delay boot. The passage could be improved:-

1. There is another, simpler and safer method to prevent a slow startup by '''chronyd''' that could be listed first and avoids dealing with the expressed danger of editing {{Path|/etc/inittab}} wrongly and its implied stunting of system boot.

The method has been suggested helpfully in various places:
* In the second paragraph of the file to be edited: {{Path|/etc/conf.d/chronyd}}
* https://whynothugo.nl/journal/2023/11/19/setting-up-an-alpine-linux-workstation/#chronyd-blocks-at-startup
* https://gist.github.com/c0m4r/e38d41d0e31f6adda4b4c5a88ba0a453#NTP

The method is to edit {{Path|/etc/conf.d/chronyd}} and to change the line {{Codeline|1=FAST_STARTUP=no}} to {{Codeline|1=FAST_STARTUP=yes}}.

2. Technically, '''chronyd''' is not a boot service but rather launches at the default level ({{Codeline|rc-update add chronyd default}}), so the subheading may need to be improved. There is [https://wiki.alpinelinux.org/w/index.php?search=%22%5B%5B%23Preventing+slow+services+from+delaying+boot%7C%22&title=Special%3ASearch&profile=default&fulltext=1 only one wiki page] that links to that subheading, and it is in this very same OpenRC wiki page, so it should be easy to change the subheading title, say, from ''"Preventing slow services from delaying boot"'' to ''"Preventing slow services from delaying system launch"'' or ''...system startup''. The link is mentioned twice in this wiki page, so those passages could be reviewed:
* https://wiki.alpinelinux.org/wiki/OpenRC#Stacked_runlevels
* https://wiki.alpinelinux.org/wiki/OpenRC#Configuration

Alternatively, an ''Include:Chronyd - Startup Speed Enhancement'' page could be started for inclusion here and wherever else (Any future ''Chrony'' page, for example) that would include the current inittab method and the FAST_STARTUP method.
[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 16:21, 8 August 2025 (UTC)

:Please note also that the external link about the {{Path|inittab}} method, [https://ptrcnull.me/posts/openrc-async-services/ OpenRC: Start services after login prompt], is now broken. Please consider whether perhaps the reference/attribution is suitable, as it stands. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 16:33, 8 August 2025 (UTC)
:[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]])

:: Thanks for submitting a thorough feedback. Highly appreciated. I have fixed the external links and internal links and updated section heading as per your suggestion. Service '''chrony''' was meant to be example to explain the concept. For now i've removed the word chrony. Regarding adding {{Codeline|1=FAST_STARTUP=yes}} to Chrony page, i'm quite hesitant to touch pages where i lack knowledge. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 20:02, 8 August 2025 (UTC)

The below Note may add confusion to users. Please consider rewording or removal.
{{Note|The upstream OpenRC User Guide for user services considers [https://github.com/OpenRC/openrc/blob/master/user-guide.md#auto-starting configuring pam] in the management of user service sessions; as an experimental branch of OpenRC, this facility, including its autostart configuration, may be fluid. Many Alpine Linux installations typically may not run pam.}}
* The experimental is already there "User services are currently experimental ". If necessary that can be '''highlighted'''.
* I request a rewording to tell user on what he's supposed to do for pam. In the current form, the Note does not help the user on how to proceed.
- [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 11:03, 11 August 2025 (UTC)

::- Thank you for your kind attention on the wiki. I have tried to address your concern by removing the note plus the reference to it under [[OpenRC#PAM_support|PAM support]] instead of elaborating on the upstream OpenRC configuration user guide passage regarding pam.

::- On a different topic, while hoping to keep the wiki a clear user guide, do we want to simultaneously reference more in-depth examinations about user services that may be significant to developers? For example, consider a possible closing passage under ''User Services'', or under a new ''Further reading'' section, or perhaps in a briefer form under ''See also'':

:::'For a more in-depth examination of OpenRC user services, consider useful discussions regarding DE-dependent (''desktop environment'') vs DE-independent environment variables discussed in an [https://github.com/OpenRC/openrc/pull/723 upstream thread] about user services, and whether the variables ought to be passed on filtered (not in whole) or not. Other useful assessments were laid out in an excellent though now [https://wiki.gentoo.org/wiki/OpenRC/Legacy_user_services outdated Gentoo wiki page] about legacy user services that furthermore had examined {{pkg|wlsunset}} when used as a user service in Wayland; their current [https://wiki.gentoo.org/wiki/OpenRC#User_services User Services page] adds further useful and more up-to-date contributions.'

::This passage could be left here for any further discussion or added to the wiki with or without any edits, as may be seen to be suitable; I am grateful either way.

::- Perhaps one should consider moving the paragraph about allowing parallel services into the section '''Preventing slow services from delaying system startup''', as a subheading called "Parallel services". It could be placed after the introductory paragraph, "Services that take a while to start will block ...". This ''parallel services'' passage is not immediately relevant in its current location as the second paragraph about OpenRC configuration. It may simply appear there from early days in the preparation of the page.

::The suggestion that currently appears there could then be listed as a second subheading (after the "Parallel services" subheading suggested above), to be titled, say, "Async runlevel method", "Stacked runlevel method", "Inittab method" or as suitable.

::- Are we satisfied to keep the [[OpenRC#Command_usage|Command usage]] section where it is, deep down on this page, or would it be more pertinent to give command usage examples nearer to the introductory section of the wiki page, perhaps at the beginning of [OpenRC#Quickstart|Quickstart] table or immediately after it (retaining the ''Command usage'' subheading or not)? Perhaps this ''Command usage'' passage has suffered displacement from newer passages.

::This passage could additionally illustrate the most commonly used OpenRC commands at the beginning of the Quickstart section with a handful of complete {{ic|rc-service}} and {{ic|rc-update}} command line instructions; otherwise, full examples of common OpenRC clis first appear in the disproportionally long ''User Services'' section, and OpenRC instructions are otherwise introduced quickly, with no complete cli example, in the current ''QuickStart'' table:

'''Commonly-used OpenRC commands'''
Start, stop (or {ic|restart}}) a service, for example, at the boot runlevel (do not use employ the '<' nor '>'):
{{cmd|doas rc-service <serviceName> start boot}}
{{cmd|doas rc-service <serviceName> stop boot}}
Add or delete a service to/from the sequence of services that need to start automatically in future sessions at the {{ic|default}} runlevel; note that the '''default''' runlevel is assumed, so it does not need to be stated explicitly:
{{cmd|doas rc-update add <serviceName> default}}
{{cmd|doas rc-update del <serviceName>}}
List the current statuses of all services; however, do not use {{ic|doas}} nor the equivalent command as root to display the statuses of any ''user service'':
{{cmd|doas rc-status}}
List the assigned runlevels of all services; likewise, do not use {{ic|doas}} nor root to display the runlevels of user services:
{{cmd|doas rc-update}}

::Alternatively, the above ''Commonly-used OpenRC commands'' passage, with or without any edits as may be seen to be suitable, could simply not be included.

::- The current passage in [[OpenRC#Command_usage|Command usage]], "To view the command usage for all OpenRC commands (rc-update, rc-service, rc-status, openrc etc.) use the --help or -h flag [...]" could be moved into the Quickstart section instead of leaving it near the end of the page.

::- The ''Command usage'' section further contains a paragraph that is irrelevant to OpenRC: 'The busybox command equivalent for traditional GNU/Linux systems is as follows [...]'. This paragraph would be more relevant, if at all, for example:-
::* In the [[BusyBox]] page, if suitable; or
::* In the [[Comparison_with_other_distros 'Rosetta Stone']] page, perhaps under a new heading there, say, ''Userspace commands'' or ''Command line instructions'', seeing how, currently, there are only sections for ''Package management'', ''Runlevel & Initscripts'' and ''Config files''; or
::* Being culled from this page.

::Thank you. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 21:44, 11 August 2025 (UTC)
::: Thanks once again for the detailed suggestions. Hope i've done everything as suggested. Please make necessary amends, if i have missed out something. Highly appreciated. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 10:03, 12 August 2025 (UTC)

== Warning in PAM support ==

Dear [[User:WhyNotHugo]], I'm not sure about the need for warning in the PAM support section. I have been using User services with PAM support for the past few months without any issues and i have not seen any bug reports filed regarding this. btw:i'm using pamrundir and i tested dwm with the manual XDG_RUNTIME_DIR script as added there. I believe Warning should be sparingly used in Wiki, if there are unresolved/known issues. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 15:59, 5 September 2025 (UTC)

:[[User:Prabuanand]] This was solved shortly after your comment, thanks. Feel free to remove this talk subsection. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:32, 24 March 2026 (UTC)

== User Services -> Runlevels ==

Dear [[User:WhyNotHugo]], This section probably requires some rewriting.
* I'm not sure when this sysinit runlevel is used/required "mkdir -p ${XDG_CONFIG_HOME:-~/.config}/rc/runlevels/sysinit".
* in the command openrc -U $RUNLEVEL. Instead of $RUNLEVEL, consider using <> as [[Help:Reading#Placeholder|placeholder]].
* Will adding "exec openrc -U gui" to ~/.profile support both Wayland and Xorg? Shouldn't the Compositor startup file be used for this for wayland? --[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 16:13, 5 September 2025 (UTC)
:I just now tested adding "exec openrc -U gui" to ~/.profile and i got locked out with "XDG_RUNTIME_DIR unset". Only after removing this, i could login to tty. Sway too did not start with this option. Here are my [git.sr.ht:~prabuanand/dotfiles dotfiles] for reference. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 16:55, 5 September 2025 (UTC)

::[[User:Prabuanand]]: Using '''exec openrc -U gui''' in '''~/.profile''' would be too early, DISPLAY or WAYLAND_DISPLAY would not be set, and services which rely on those would fail to start. We might want to clarify this explicitly. XDG_RUNTIME_DIR needs to be set before any service that relies on it (including the compositor) [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:37, 24 March 2026 (UTC)
:::Dear [[User:WhyNotHugo]], i think this entire paragraph is entirely not needed. The old instructions https://wiki.alpinelinux.org/w/index.php?title=OpenRC&oldid=30771#User_services was guaranteed to work. When you added this paragraph, i tested it once, found it to be not working in my setup. Since i don't use .profile and zsh/bash, i did not want to remove it myself. - [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 16:46, 24 March 2026 (UTC)
::Dear [[User:WhyNotHugo]], Thank you for your excellent contributions to Linux, and to Alpine Linux in particular. I support [[User:Prabuanand|Prabuanand]]'s excellent and extensive impressions/observations above however, including those further above in the 'Warning in PAM support' discussion. I would be grateful for your input about them.

::Additionally, I suspect that two further points of guidance in your edits warrant review or elaboration on the wiki page:-
::*Your claim that '''sysinit''' is the default level; please elaborate why '''default''' would not be the default runlevel here, for my better understanding and for the sake of newcomers to Alpine Linux's wiki.
::*Note also that your instruction did not revert the runlevel back to '''sysinit''' on my system, even with the user ('''-U ''') switch: {{Cmd|$ openrc -U}}
::*Your edit proposing a command to revert to the sysinit runlevel appears to run contrary to the guidance [[OpenRC#Runlevels|currently in the wiki]], that ''"sysinit always runs when the host first starts and should not be run again."''
::Thanks again for your help addressing our concerns. [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 17:43, 12 September 2025 (UTC)

:::'''sysinit''' is used by default when you don't explicitly specify another runlevel. My statement describes the behaviour of OpenRC itself, it's not my decision. I've talked to navi about it, and it seems to not be intentional, but it's still the current behaviour. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:37, 24 March 2026 (UTC)

Dear [[User:StruanR]],
I am grateful for your improvements of the wiki, kindly continue them! Please note that certain edits, however, changing a root prompt to a user prompt, were in various cases inaccurate, and I have reverted those. Perhaps the wiki could be made clearer that to modify ''system'' services or runlevels, one generally requires a root prompt or doas/sudo; to display/check those, a user prompt may suffice. Note, on the other hand, that to modify ''user'' services (using the '''-U''' switch), a root prompt or doas/sudo would not generally be used. I hope this helps.
Your other edits were helpful, thank you!
I took the chance to amend some previous passages made by other helpful contributors while I was at it. Please continue helping out with the wiki! [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 17:43, 12 September 2025 (UTC)

:: +1, we should have a dedicated page for OpenRC User services. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 16:37, 24 March 2026 (UTC)

Software management

2026-03-14T10:14:22Z

Prabuanand: made changes to various sections to improve the readability. added wikitags like Todo and Tips

This page documents various ways to [[#Running glibc programs|run software compiled with glibc]] and to manage software using [[#Graphical software manager|graphical software managers]] in Alpine Linux. There are pages elsewhere regarding compiling [[Compile software from source|software from source]] and for creating a [[Custom Kernel|custom kernel]].

== Alpine package keeper ==
{{Main|Alpine Package Keeper}}
The official package manager in Alpine Linux, [[Alpine Package Keeper|Alpine Package Keeper(apk)]], is a ''cli'' tool. [[Comparison_with_other_distros#Comparison_chart/Rosetta_Stone|Rosetta stone]] shows how standard package management tasks are done in Alpine Linux compared to other popular distributions.

== Graphical software manager ==

The following graphical tools are available to manage official software packages from Alpine Linux [[Repositories|repositories]] and [[#Flatpak|flatpaks]] instead of using the [[#Alpine Package Keeper|cli-based apk tool]].

=== GNOME software ===

[[GNOME#Configuration|GNOME software]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

=== KDE Discover ===

[[KDE#Discover|KDE Discover]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

== Flatpak ==
{{Main|Flatpak}}

[[Flatpak#Installing_Flatpak|Flatpaks]] are by far the easiest method for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. To use flatpaks, ensure that the [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.

== AppImage ==
{{Main|AppImage}}

[[AppImage|AppImages]] are another alternative to [[Flatpak|flatpaks]] for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. However, not as many AppImages work on Alpine Linux as compared to Flatpaks, since AppImages are more commonly built for glibc operating systems, as opposed to Alpine Linux's use of musl.
Refer to the [[AppImage]] page for prerequisites and for detailed instructions to run AppImages in Alpine Linux.

== Coldbrew ==

'''Coldbrew''' is a package manager that can install Alpine Linux aports Edge packages without needing root access, somewhat similar to '''brew'''. This is particularly useful on immutable operating systems such as with [https://postmarketos.org/blog/2025/10/12/pmOS-update-2025-09/#immutable-postmarketos PostmarketOS's duranium image]. '''Coldbrew''' is available in Alpine Linux Edge testing repository as of January 2026; the testing repository is [[Repositories#Using_testing_repository|recommended to be tagged]] if installing '''coldbrew''' on any supported Alpine Linux release.

'''Coldbrew''' replaces the [https://github.com/kcxt/iced '''iced'''] package on Alpine Linux, which used the {{Pkg|mkosi-sandbox}}; packages run inside a chroot using '''bubblewrap''' instead. They have access to the home directory, but have only controlled access to all other files through explicit bind mounts. Packages installed using '''coldbrew''' are referred to as tools. See [https://gitlab.postmarketos.org/postmarketOS/coldbrew further details upstream].

To install '''coldbrew''':
{{Cmd|$ doas apk add coldbrew@testing}}

To install a tool to be run by '''coldbrew''', say, {{Pkg|corepad}}:
{{Cmd|$ coldbrew install corepad}}

Note that even though the output ends...

Installed binary /usr/bin/corepad

...the path being referred to exists within a new mount namespace using bind mounts in the '''bubblewrap''' sandbox.

A wrapper program is installed to {{Path|~/.local/bin}} on Alpine Linux.

To run the tool under '''coldbrew''':
{{Cmd|$ coldbrew run corepad}}

To remove the tool:
{{Cmd|$ coldbrew remove corepad}}

All installed tools can be listed through the {{ic|$ coldbrew ls}} command.

== Running glibc programs ==

If you want to run [https://www.gnu.org/software/libc/ glibc] programs in Alpine Linux, there are a few ways of doing so.

For simpler binaries, you can install [[#gcompat|gcompat]], which is a compatibility layer; or you could do it the easy way and use [[#Flatpak|Flatpaks]] or [[#AppImage|AppImages]]. See [[#Containers|containers]] or the [[#Chroot|chroot]] section for ways to run glibc programs, including graphical ones such as {{ic|VSCode}}, {{ic|google-chrome}}, {{ic|obsidian}}, etc.

=== gcompat ===

[https://git.adelielinux.org/adelie/gcompat gcompat] is a library that provides glibc-compatible APIs for use on musl libc systems such as Alpine Linux. To install, issue the command: {{cmd|$ doas apk add {{pkg|gcompat}}}}
After that, you run your binaries as normally.

For an usage example, refer to the [[Firefox#DRM_content_using_Widevine_workaround|Firefox]] page where gcompat is used to run the glibc-compiled Widevine binary.

== Chroot ==
{{Main|Chroot}}

Glibc applications can be run by installing a glibc-based distribution in a chroot inside the Alpine Linux.

Instructions for setting up chroot for following popular glibc distributions are available:
* [[#Gentoo Linux|Gentoo Linux]]
* [[#Arch Linux|Arch Linux]]
* [[#Debian|Debian]]

For updating the chroot, or for installing packages and their dependencies using package manager like {{ic|apt-get}}, enter the chroot as root.

The following instructions are for a Debian chroot in {{Path|/var/chroots/debian}}, on x86_64, but can be adapted to other systems by using the appropriate paths.
{{cmd|$ doas mount --bind /dev /var/chroots/debian/dev
$ doas mount --bind /proc /var/chroots/debian/proc
$ doas mount --bind /dev/pts /var/chroots/debian/dev/pts
$ doas chroot /var/chroots/debian /bin/bash
[chroot]# apt update && apt upgrade}}

After installing the necessary applications and whatever else you might do, exit the chroot:
{{cmd|[chroot]# exit}}

Then, unmount the binds for /dev/pts, dev and proc to avoid issues:
{{cmd|$ doas umount /var/chroots/debian/dev/pts
$ doas umount /var/chroots/debian/dev
$ doas umount /var/chroots/debian/proc}}

{{Tip|The most reliable way to enter and exit a chroot is to use the [[Chroot#Enter_chroot|start-chroot]] script, where the script takes care of all mounting and unmounting.}}

Once a chroot is ready, there are at least a couple of ways to run glibc applications.
* [[#Using the glibc dynamic linker|Using the glibc dynamic linker]]
* [[#Bubblewrap + Chroot|Bubblewrap + Chroot]]

=== Using the glibc dynamic linker ===
{{Todo|Please test and confirm if the below instructions are complete or requires modification.}}
The glibc dynamic linker can be configured in Alpine as follows. These instructions are for a Debian chroot in {{Path|/var/chroots/debian}}, on x86_64, but can be adapted to other systems by using the appropriate paths.

{{cmd|<nowiki># mkdir -p /lib64
# ln -s /var/chroots/debian/lib/x86_64-linux-gnu/ld-linux-x86-64.so.2 /lib64
# printf '/var/chroots/debian/lib/x86_64-linux-gnu\n/var/chroots/debian/usr/lib/x86_64-linux-gnu\n' > /etc/ld.so.conf
# /var/chroots/debian/sbin/ldconfig</nowiki>}}

=== Gentoo Linux ===

Select a ''stage3'' from [https://www.gentoo.org/downloads/ here] and the ''portage'' latest from [https://www.gentoo.org/downloads/mirrors/ here] at gentoo/snapshots/portage-latest.tar.xz.

First,{{cmd|$ doas apk add {{pkg|xz}}}}

Enter the chroot:
{{cmd|$ mkdir ~/chroot
$ cd ~/chroot
$ doas tar -xvf stage3-*.tar.xz
$ doas tar -xvf portage-latest.tar.xz
$ doas mv portage usr
$ doas mount --bind /dev dev
$ doas mount --bind /sys sys
$ doas mount -t proc proc proc
$ doas cp /etc/resolv.conf etc
$ doas chroot . /bin/bash}}

And voilà, you have your working Gentoo chroot! 

You can now take a look at [https://wiki.gentoo.org/wiki/Handbook:Main_Page Gentoo's Handbook] to find out how you can configure and install your system, or simply extract/copy the program that you need to run in your chroot environment, and then execute it.

Here is a wrapper script that is similar to {{ic|arch-chroot}} when you frequently reuse this chroot. Also, create an account with the same username as host current user to the chroot, or make changes to the {{ic|userspec}} option to chroot line:

{{Cat|gentoo-chroot.sh|<nowiki>#!/bin/bash
CHROOT_PATH="/home/$USER/chroot"
cd $CHROOT_PATH
mount | grep $CHROOT_PATH/dev || doas mount --bind /dev dev
mount | grep $CHROOT_PATH/sys || doas mount --bind /sys sys
mount | grep $CHROOT_PATH/proc || doas mount -t proc proc proc
doas cp /etc/resolv.conf etc
doas chroot --userspec=$USER:users . /bin/bash
echo "You must manually unmount $CHROOT_PATH/dev, $CHROOT_PATH/sys, $CHROOT_PATH/proc."
</nowiki>
}}

Do {{ic|$ chmod +x gentoo-chroot.sh}} to make it executable.

=== Arch Linux ===

{{Seealso|Installing ArchLinux inside an Alpine chroot}}
Either use '''pacstrap''' (included with the arch-install-scripts package) or an Arch bootstrap image:

{{cmd|$ doas apk add {{pkg|arch-install-scripts}}
$ mkdir ~/chroot && cd ~/chroot
$ curl -O https://mirrors.edge.kernel.org/archlinux/iso/latest/archlinux-bootstrap-x86_64.tar.zst
$ doas tar -x --zstd -f archlinux-bootstrap-x86_64.tar.zst && rm archlinux-bootstrap-x86_64.tar.zst
$ doas sed -i '/evowise/s/^#//' root.x86_64/etc/pacman.d/mirrorlist
$ doas sed -i '/CheckSpace/s/^/#/' root.x86_64/etc/pacman.conf
$ doas arch-chroot root.x86_64
[chroot]# pacman-key --init
[chroot]# pacman-key --populate archlinux}}

Once that is done, update the system and install the desired package(s) (denoted by ''"foo"'' in this example):

{{cmd|[chroot]# pacman -Syu <var>foo</var>}}

=== Debian ===

Alpine Linux provides the {{pkg|debootstrap}} package to create the Debian chroot. Here are the steps: {{cmd|$ doas apk add debootstrap
$ doas mkdir -p /var/chroots/debian
$ doas debootstrap --arch amd64 stable /var/chroots/debian/ https://deb.debian.org/debian}}

The {{ic|--arch}} is optional, depending on your needs. Instructions for entering and exiting the Debian chroot are given in the [[#Chroot|Chroot]] section above.

== Containers ==

=== Distrobox + Podman ===

[[Distrobox]], combined with [[Podman|podman]] container running in rootless mode, allows to easily run [[Distrobox#Running_graphical_programs|glibc-compiled graphical programs]]. This will not require root privileges once set up.

=== Bubblewrap + Chroot ===

Shell aliases are used to create a container with [[Bubblewrap]] with [[#Chroot|Chroot]] as its content. Once the graphical glibc packages are installed inside the chroot, this allows for running them without requiring root privileges using bwrap.

* [[Install]] the {{pkg|bubblewrap}} package.
* Follow the instructions to set up a [[#Chroot|Chroot]]. For eg. [[#Debian|Debian chroot]].
* Install necessary glibc applications inside the chroot as root either using package manager like {{ic|apt-get}} or otherwise.
* Create alias {{ic|glibc}} and/or {{ic|glibcX11}} using bwrap in the Alpine Linux host as regular user.

{{cmd|$ alias glibc{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group"}}

{{cmd|$ alias glibcX11{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group --bind /tmp/.X11-unix/X0 /tmp/.X11-unix/X0 --setenv DISPLAY :0"}}

To run programs that use X11/Xorg, you might need to use {{ic|xhost}} on the Alpine Linux host in order to allow local connections. For example:{{cmd|$ doas xhost + local:}}

Now we can invoke any glibc_binary from the chroot using the above alias from the Alpine Linux host, as follows:
{{cmd|$ glibc glibc_binary}} or {{cmd|$ glibcX11 glibc_binary}}

When a [[Wayland]] desktop such as [[Sway]] runs without XWayland on the Alpine Linux host, Electron apps need to be started with certain flags. These flags enforce Wayland rendering.
* For VS Code:
{{cmd|<nowiki>glibc code --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}
* For Google Chrome:
{{cmd|<nowiki>glibc google-chrome --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

{{Tip|The Bubblewrap aliases are sufficient only for running applications. To install, remove, or update software within the chroot, follow the steps described in the [[#Chroot|Chroot]] section.}}

== See also ==

* [[Alpine Package Keeper]]
* [[Installing ArchLinux inside an Alpine chroot]]
* [[Compile software from source]]
* [[Kernels]]

[[Category:Package Manager]] [[Category:Development]]

Diskless Mode

2026-02-28T11:34:08Z

Prabuanand: added clarification on the need for two media. refer redd.it/1rgyl6p

In Diskless mode, the entire operating system with all applications are first loaded into RAM (<code>tmpfs</code>) and then only run from there. This is also the method used to boot the Alpine Linux <Code>ISO9660</Code> filesystem based read-only [[Installation#Preparing_installation_media|installation media]].

Diskless mode is extremely fast and can save on unnecessary disk spin-ups, power, and wear and suitable for servers. It is similar to what other linux distributions may call a "frugal" install or boot using a "toram" option.

Alpine Linux provides [[Alpine_local_backup|Local Backup Utility]]({{ic|lbu}}) that allows custom configurations and package installations to be optionally preserved or made to "persist" across reboots as [[#Apkovl|apkovl]] files on persistent storage.

If additional or updated packages have been added to the system, these may also be made available for automatic (re)installation during the boot phase without any (re)downloading, by enabling a [[#Local package cache|local package cache]].

== Diskless installation ==

When running the <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> script, if "disk=none" is specified, then Alpine Linux will continue to run in diskless mode. It invokes <code>[[Alpine_setup_scripts#setup-lbu|setup-lbu]]</code> and <code>[[Alpine_setup_scripts#setup-apkcache|setup-apkcache]]</code> to use any available writable filesystem on any media other than the read-only installation media for saving the configuration settings as apkovl file and local package cache.

{{Tip|If you are using a single USB flash drive for a diskless install, use a [[#Using customizable boot device for persistent storage|customizable boot device]] rather than standard read-only installation media. This allows the drive to host both the OS and your persistent storage.}}

Complete the below preparatory steps depending on the available persistent storage option for apkovl and local package cache. Persistent storage are configured as read-only in {{Path|/etc/fstab}}, as [[Alpine_local_backup|lbu]] can temporarily remount them as writable for their operation.

=== Using customizable boot device for persistent storage ===

A [[Create_a_Bootable_Device|Customizable boot device]] allows Alpine Linux to boot and run in Diskless mode from a partition with a writable filesystem on USB-Stick/CompactFlash/SDCard or SSD/NVMe harddisk. The [[#Apkovl|apkovl]] file(s) and [[#Local package cache|local package cache]] can be stored in this customizable boot device and no other storage is required.

# Boot using the [[Create_a_Bootable_Device|Customizable boot device]].
# Find out where the customizable boot device is mounted, the location could vary.{{Cmd|<nowiki># mount | grep /media
/dev/sdXY on /media/sdXY type vfat (rw,relatime,fmask=0022,dmask=0022,codepage=437,iocharset=utf8,shortname=mixed,errors=remount-ro)
</nowiki>}}
# Mount the customizable boot device in rw mode, if required. {{Cmd|# mount -o remount,rw /media/sdXY}}
# Proceed to [[#Finishing diskless installation|Finishing diskless installation]] section without rebooting the computer.

=== Using an internal disk for persistent storage ===

Storing local configs on '''internal disks''' requires manual steps, i.e making an entry in {{Path|/etc/fstab}}, create mountpoint, and mount the partition before running <code>setup-alpine</code> script due to Issue [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10473 #10473]. Use only ext4 filesystem partitions on classic drives to store diskless mode states as diskless setup currently doesn't work on btrfs and xfs filesystems, or nvme-based devices as per {{Issue|11589|}}.

# In this case, boot the target diskless system from the installation media and do not proceed after the [[Installation#Boot_Process|boot process]] stage.
# If necessary partition(s) are unavailable, manually [[Setting_up_disks_manually#Creating_partitions|create]] a partition using <Code>fdisk</Code>. In the below steps, we will use /dev/sdXY as partition number. Adjust the partition identifier as per the output of {{Codeline|<Code>blkid</Code>}} 
#* mkfs.ext4 creates ext4 filesystem with 64bit feature enabled by default, but extlinux may not be able to boot with that due to Issue {{Issue|14895}}. You may need to add "-O ^64bit" to mkfs.ext4 to circumvent this. The below command creates an ext4 partition with disabled journaling, to reduce write operations and allow the disk to spin down after the .apkovl and the packages have been read from the partition during the boot. Install package {{pkg|<Code>e2fsprogs</code>}} using command {{Codeline|<Code>apk add e2fsprogs</Code>}}, if the command <Code>mkfs.ext4</Code> is not available.
#: {{Cmd|# mkfs.ext4 -O ^has_journal,^64bit /dev/sdXY}}
# Configure the /etc/fstab to mount the writable partition to /media/sdXY conforming to the hot/cold-plug mountpoints.
#: {{Cmd|# mkdir /media/sdXY}}
#: {{cmd|# echo "/dev/sdXY /media/sdXY ext4 noatime,ro 0 0" >> /etc/fstab}}
# Mount the partitions listed in {{Path|/etc/fstab}}:{{Cmd|# <code>mount -a</code>}}
# Verify that the changes have been applied correctly by looking at the output of {{Cmd|$ <code>mount</code>}}
# Proceed to [[#Finishing diskless installation|Finishing diskless installation]] section without rebooting the computer.

=== Finishing diskless installation ===

# If <code>setup-alpine</code> has not run before, follow the [[Installation#Installation_Step_Details|Installation steps]] to complete until the '''Disk & Install''' option appears.

# When the ''' Disk & Install''' option appears, the preparatory steps done earlier for [[#Using an internal disk for persistent storage|internal disk]] or [[#Using customizable boot device for persistent storage|customizable boot device]] should now enable you to choose the partition('''sdXY''') for saving the local configs and package cache. So accept the choices as follows:{{Cmd|<nowiki>Which disk(s) would you like to use? (or '?' for help or 'none') [none]
Enter where to store configs ('floppy', 'sdXY', 'usb' or 'none') [sdXY]:
Enter apk cache directory (or '?' or 'none') [/media/sdXY/cache]:</nowiki>}}
# If <code>setup-alpine</code> has already been run to configure the diskless system, the storage and package cache settings can be configured using the <code>[[Alpine_setup_scripts#setup-lbu|setup-lbu]]</code> and <code>[[Alpine_setup_scripts#setup-apkcache|setup-apkcache]]</code> as follows:{{cmd|<nowiki># setup-lbu sdXY
# mkdir /media/sdXY/cache
# setup-apkcache /media/sdXY/cache</nowiki>}}
# After the installer finished one can see how many created/modified files are detected and will be added to the backup:{{Cmd|<nowiki># lbu status
# lbu status | wc -l
59
</nowiki>}}
# Now Commit all the changes using the command:{{Cmd|# lbu commit}}
# Verify that the above command has created the [[#Apkovl|apkovl]] file i.e <Code><hostname>.apkovl.tar.gz</Code> as follows:{{Cmd|<nowiki>ls -l /media/sda1/*apkovl.tar.gz
-rwxr-xr-x 1 root root 9591 Oct 19 15:23 /media/sda1/foo.apkovl.tar.gz
</nowiki>}}
# Now the diskless installation can be considered complete.

== Configuration ==

Refer to the following sections related to running a Diskless installation.

=== Modifying root filesystem size ===

In Diskless mode, the root filesystem is mounted as <code>tmpfs</code>. By default rootfs is allocated 50% of available RAM (without swap). This may be adjusted to arbitrary value (like 300MB) temporarily after boot by issuing <code>mount -o remount,size{{=}}300M /</code>, or permanently at boot by setting [https://gitlab.alpinelinux.org/alpine/mkinitfs/-/blob/54bae0769080710e0769370a7bf3e0e158eec152/initramfs-init.in#L809-813 kernel parameter] as <code>rootflags{{=}}size{{=}}300M</code>.

=== Local package cache ===
{{Main|Local APK cache}}
When Alpine Linux boots in Diskless Mode, the remote repositories will not be available until after networking has started. That means newer or extra packages not in your local boot media's squashfs image would not be available after a reboot, unless they were made available as [[Local APK cache|local package cache]] on a writable local storage device. The local package cache can be on the same partition as the '''apkovl''' file.

=== Apkovl ===

The local configuration or system state is saved as APK Overlay ('''apkovl''') file to a backup location by the {{ic|lbu}}and loaded when booting. The filename for the '''apkovl''' file is of the format <Code><hostname>.apkovl.tar.gz</Code> and is stored in a location whose path is defined in {{Path|/etc/lbu/lbu.conf}} file. Apkovl file stores all configuration files that have changed from the default ones. The contents from the Apkovl file are overlaid on top of the contents of the base image. In Diskless mode, for every change made to the running system to persist across reboot, the command {{ic|lbu commit}} must be issued to update the apkovl file.

==== Loading apkovl from webserver ====

If a read-only installation media is used, it can remain the only boot device for the "diskless" system by saving the running state i.e [[#Apkovl|apkovl]] file to a webserver, and have these automatically loaded when booting from the boot device. The Alpine linux boot process supports passing boot parameters to load [[#Apkovl|apkovl]] file from a webserver, by supplying a custom url with the {{ic|apkovl}} kernel boot parameter. If you don't have a web server you can run busybox's httpd temporarily to serve an .apkovl - <code>busybox httpd -p 127.0.0.1:80</code>.

== Upgrading a diskless system ==

[[Alpine_Package_Keeper#Upgrade_a_Running_System|Upgrading a running]] system with [[Diskless Mode|diskless]] or [[Data Disk Mode|Data disk]] mode for regular package update requires running the below command from [[Alpine_local_backup|Local Backup Utility]] after every package update:{{Cmd|# lbu commit}}

For upgrading the kernel, with its modules and firmware files use [[Diskless Mode#update-kernel script|update-kernel]] script. For upgrading [[Diskless Mode|diskless]] or [[Data Disk Mode|Data disk]] installations to a new release branch refer [[Upgrading Alpine Linux to a new release branch#Upgrading diskless and data disk mode installs to latest release|Upgrading diskless and data disk mode installs to latest release]].

=== update-kernel script ===

When kernel packages with its modules and firmware packages are upgraded, the <code>update-kernel</code> script generates initfs images and installs them together with upgraded kernel and updates the boot files in persistent storages like [[Create_a_Bootable_Device|customizable boot device]].

* Before upgrading, install the {{Pkg|mkinitfs}} package as this is required for the generation of the initial filesystem used during boot as follows: {{cmd|# apk add mkinitfs}}
* Additional initfs features that are missing in the default configuration, like the [[Btrfs|btrfs]] filesystem support (at the time of writing, to allow loading .apkovl configs and package cache during boot), may be enabled in the file {{Path|/etc/mkinitfs/mkinitfs.conf}}.
* Available initfs features may be listed with <code>ls /etc/mkinitfs/features.d</code>
{{cmd|<nowiki># ls /etc/mkinitfs/features.d
# apk add nano
# nano /etc/mkinitfs/mkinitfs.conf
# lbu commit
</nowiki>}}
* Finally update the kernel and its boot environment.
{{cmd|# update-kernel /media/sdXY/boot/
}}
{{Note|<code>update-kernel</code> run needs at least 8 GB free ram memory to avoid a broken modloop-image. So, in memory constrained devices like [[Raspberry Pi]], use the environment variable <code>TMPDIR</code> to point to a directory on a *nix file system formatted physical device, like a SD-Card or USB-Stick as follows: {{Cmd|<nowiki># TMPDIR=/media/sdc1/tmp update-kernel /media/mmcblk0p1/boot/</nowiki>}}}}

See <code>update-kernel --help</code> for options to manually add additional module or firmware packages.

== Documentation on kernel options ==

Documentation about kernel command line options regarding diskless mode can be accessed by installing the documentation sub-package {{Pkg|mkinitfs-doc}} and running the command {{Cmd|man mkinitfs-bootparam}}

<Pre>
If no root= parameter is given, the initramfs will build a live system
in memory from scratch. This is also called diskless mode.

When booting in diskless mode, the following options are also
available:

alpine_repo=(URL | PATH)
If set, /etc/apk/repositories will be filled with this. May be a
comma-separated list of URLs.

apkovl=(URL | [DEVICE[:FS_TYPE]:]PATH)
A HTTP, HTTPS or FTP URL to an apkovl.tar.gz file which will be
retrieved and applied. Can also be a filesystem path, optionally
prepended with the device name without the /dev/ prefix.

autodetect_serial=no
Disable automatic detection and setup of serial console.

ds=OPTIONS
Data source for tiny-cloud. If OPTIONS starts with nocloud,
tiny-cloud will be enabled.

nokeep_apk_new
Setup a fresh system, ignore any apkovl.

pkgs=PACKAGE{,PACKAGE}
Comma-separated list of packages to be installed.
ssh_key=(URL | SSH_KEY)
This setting installs openssh and places the public key given as
value in /root/.ssh/authorized_keys. If the value is an HTTP or
FTP url, its fetches the key(s) from there.

splash Enable splash screen.

usbdelay=NUMBER
Wait NUMBER seconds for USB devices to show up before searching
for boot media.

wireguard=INTERFACE;IP_ADDRESS{,IP_ADDRESS,...}[;WG_CONFIG_FILE]
Set up a wireguard interface named INTERFACE with the addresses
IP_ADDRESS and use /etc/wireguard/initrd.conf or WG_CONFIG_FILE
as a classic wg (not wg-quick) config.

zfs_force=NUMBER
Enable force importing the root zpool on boot, even if it was
previously mounted from a different system/OS.
</Pre>

== See also ==

* [[Alpine_local_backup|Alpine Local backup Utility - ''lbu''']]
* [[Local APK cache|Local package cache]]
* [[Manually editing a existing apkovl]]
* [[Back Up a Flash Memory Installation]]
* [[Upgrading_Alpine#Upgrading_Alpine_Linux_on_other_removable_media_(such_as_CF/USB)|Upgrading Diskless to New Alpine Linux Release]]
* [[PXE boot#Specifying an apkovl|Diskless PXE Boot]]
* [[How to make a custom ISO image with mkimage]]
* [[QEMU#Live_mode|QEMU Diskless example]]
* [[Alpine local backup#Include special files.2Ffolders to the apkovl|Include special files section]] - To include custom files outside of <code>/etc</code> in .apkovl file.
* [[SquashFS]]
* [[OverlayFS]]
* [https://gitlab.alpinelinux.org/alpine/mkinitfs/-/blob/54bae0769080710e0769370a7bf3e0e158eec152/initramfs-init.in#L809-813 Root filesystem Size Allocation]
* [https://www.fedux.net/post/setup-alpine-linux-diskless/ Detailed Diskless Installation Instruction]
* [https://www.reddit.com/r/AlpineLinux/comments/1bezynm/comment/kuxcy70 Diskless Installation Instructions]

[[Category:Diskless]]

Tutorials and Howtos

2026-02-19T09:44:09Z

Prabuanand: removed duplicate entries

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}

'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions. Howto's have been organized in the below page based on the topics.

'''The [[#Tutorials|tutorials]] are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

{{Note|
* Contributors are requested to refer to [[Help:Editing]] first and make use of resources like [[How to write a HOWTO]].
* Contributions must be complete articles.
* Don't override already made contributions, unless there is a mistake.
* If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].}}

== Desktop ==

* {{:Daily driver guide}}

=== Networking ===

* [[Bluetooth]] - Instructions for installing and configuring Bluetooth
* [[Bonding]] - Bond (or aggregate) multiple ethernet interfaces
* [[Bridge]] - Configuring a network bridge
** [[Bridge wlan0 to eth0]]
* [[Configure Networking]]
* [[How to configure static routes]]
* Modem
** [[Using HSDPA modem]]
** [[Using serial modem]]
* [[mDNS]] - Howto implement multicast DNS resolution in Alpine.
* [[Multi ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[PXE boot]]
* Wi-Fi
** [[Wi-Fi|Connecting to a wireless access point]]
** [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* Use [https://github.com/ifupdown-ng/ifupdown-ng/blob/main/doc/interfaces-vxlan.scd vxlan], if using [[Ifupdown-ng]] instead of [[VLAN]]
* [[Setting up a Home Router]]

=== Backup and data migration ===

* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

=== Other topics ===

* [[Gaming on Alpine]]
* [[Remote Desktop Server]]
* [[Default applications|How to change default application]]
* [[CPU frequency scaling]]
* [[Mimalloc]]
* [[Enable Serial Console on Boot]]
* [[How to build the Alpine Linux kernel]]
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Setting up lm_sensors]]
* [[Fingerprint Authentication with swaylock]]
* [[Mounting a LUKS Encrypted Data Partition at Boot]]
* [[Desktop environments and Window managers|List of supported Desktop environments and Window managers]]

== Diskless ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

== Other Architectures ==

=== APU (PCEngines) ===

* [[Alpine Install: from a disc to PC Engines APU|Alpine on PC Engines APU]]
* [https://github.com/huubsch/Installation-of-Alpine-Linux-on-PC-Engines-APU3/tree/main?tab=readme-ov-file Installation of Alpine Linux on PCEngines APU, legacy BIOS]

=== ARM ===

* [[Alpine on ARM]]

==== Raspberry Pi ====

* [[Raspberry Pi|Raspberry Pi main page]]
* [[Raspberry Pi Bluetooth Speaker|Raspberry Pi - Bluetooth Speaker]]
* [[Linux Router with VPN on a Raspberry Pi|Raspberry Pi - Router with VPN]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)|Raspberry Pi - Router with VPN (IPv6)]]
* [[Classic install or sys mode on Raspberry Pi|Raspberry Pi - Sys mode install]]
* [[Raspberry Pi LVM on LUKS|Raspberry Pi - Sys mode install - LVM on LUKS]]
* [[RPI Video Receiver|Raspberry Pi - Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[Raspberry_Pi_Zero_W_-_Installation|Raspberry Pi Zero W - Installation]]
* [[How to set up Alpine as a wireless router|Raspberry Pi Zero W - Wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''

=== IBM Z (IBM z Systems) ===

* [[s390x|s390x - Installation]]

=== PowerPC ===

* [[Ppc64le|Powerpc64le - Installation]]

== Security ==

* [[#Desktop security|Desktop security]] lists steps for securing Alpine Linux desktops
* [[Setting up a laptop]] page has detailed guidelines to configure a secured laptop
* [[Securing Alpine Linux|Secure Alpine Linux]] using Security Technical Implementation Guides (STIGs)
* [[Sshguard|SSHGuard]] - Protects hosts against brute-force attacks: monitoring logs, attack detection, blocking using firewall.

== Services ==

{{Note| Services are arranged in alphabetical order.}}

=== Content management systems ===

* [[DokuWiki]] ''(Simple and easy to use wiki, no database required)''
* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[Pastebin]] ''(Pastebin software application)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[Moodle]] ''(Online Learning Management system)''

=== Database ===

* [[MariaDB]] or [[MySQL|MySQL]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Small-Time DNS with BIND9]] ''(A simple configuration with ad blocking for your home network)''
* Unbound
** [[Setting up unbound DNS server]]
** [[Using Unbound as an Ad-blocker]] ''(Setup ad blocking for your network)''
* [[TinyDNS Format]]

=== File server ===

* [[Setting up an NFS server|nfs-server]]
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''

=== Firewall ===

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]
** [[Zero-To-Awall]] -''AWall for dummies''
** [[How-To Alpine Wall]] - ''AWall for Shorewall users''
** [[Alpine Wall]] - ''AWall - Firewall management framework - Design Document''
* [[Iptables]]
* [[nftables]]
* [[Uncomplicated Firewall|Uncomplicated Firewall or UFW]]

=== HTTP and web services ===

* [[Althttpd]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]
* [[Darkhttpd]]
* [[Lighttpd]]
** [[Lighttpd Advanced security]]
** [[Setting Up Lighttpd With FastCGI]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
* [[Nginx]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
** [[Nginx with PHP]]
* Squid Proxy
** [[Setting up Explicit Squid Proxy]]
** [[Setting up Transparent Squid Proxy]] ''(Covers Squid proxy and URL Filtering system)''
** [[SqStat]] ''(Script to look at active squid users connections)''
* [[Tomcat]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎|Production LAMP system: Lighttpd + PHP + MariaDB/MySQL‎‎]]

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]
* Exim/Dovecot
** [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
** [[Setting up dovecot with imap and tls]]
* [[relay email to gmail (msmtp, mailx, sendmail]]
* [[relay email (nullmailer)]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Monitoring ===

* [[Awstats]] ''(Free log file analyzer)''
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 
* [[Linfo]]
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Logcheck]] ''(log file monitoring tool)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[Rasdaemon]] ''(Platform Reliability, Availability and Serviceability monitoring tool)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance; for alpine 3.10-3.12 only)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''
* [[Traffic monitoring]] 
** [[Setting up monitoring using rrdtool (and rrdcollect)]]
** [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[ZoneMinder video camera security and surveillance]]

=== Remote Administration ===

* ACF
** [[Changing passwords for ACF|ACF - changing passwords]]
** [[Generating SSL certs with ACF]] 
** [[setup-acf| ACF - setup]] ''(Configures ACF (webconfiguration/webmin) so you can manage your box through https)''
* [[Setting up a SSH server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator |OpenSSH 2FA]] ''(A simple two factor setup for OpenSSH)''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[Webmin]] ''(A web-based interface for Linux system)''

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== VPN ===
* [[Freeradius Active Directory Integration]]
* [[GNUnet]]
* [[IGMPproxy]]
* [[Setting up a OpenVPN server|OpenVPN server]] ''(Allowing single users or devices to remotely connect to your network)''
* [[OpenVSwitch]]
* [[Tor]]
* [[Using Alpine on Windows domain with IPSEC isolation]]
* [[Configure a Wireguard interface (wg)|Wireguard]]
* [[Vpnc]]

=== Other Servers ===

* [[apcupsd]] ''(UPS Monitoring with apcupsd)''
* [[Chrony and GPSD | Chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Glpi]] ''(Manage inventory of technical resources)''
* [[How to setup a Alpine Linux mirror]]
* [[nut-ups|NUT UPS]] ''(UPS Monitoring with Network UPS Tools)''
* [[Odoo]]
* [[Configure OpenLDAP | OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a LLDAP server|lldap-server]] ''(Directory Server)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

== Software development ==

* [[Cgit]]
* [[OsTicket]] ''(Ticket system)''
* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system) [Deprecated]''
* [[Request Tracker]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''
* [[Ansible]] ''(Configuration management)''
* [[Installing Oracle Java|Oracle Java (installation)]]

== Storage ==

* [[Setting up disks manually|Manual partitioning]]
* [[Disk Replication with DRBD|DRBD: Disk Replication]]
* [[Filesystems]]
** [[Burning ISOs]]
* [[Setting up iSCSI|iSCSI Setup]]
** [[iSCSI Raid and Clustered File Systems]]
** [[Linux iSCSI Target (TCM)|iSCSI Target (TCM)/LinuxIO (LIO)]]
** [[Linux iSCSI Target (tgt)|User space iSCSI Target (tgt)]]
* [[Setting up Logical Volumes with LVM|LVM Setup]]
** [[Setting up LVM on GPT-labeled disks|LVM on GPT-labeled disks]]
** [[Installing on GPT LVM|LVM on GPT-labeled disks (updated)]]
** [[LVM on LUKS]]
* RAID
** [[Raid Administration]]
** [[Setting up a software RAID array]]
* [[ZFS]]
** [[Root on ZFS with native encryption]]
** [[Setting up ZFS on LUKS]]
* [[CEPH|CEPH]]

== Virtualization ==

* [[Docker]]
* [[Installing Alpine in a virtual machine]]
** [[Install Alpine on VMware ESXi]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[QEMU]]
* Xen
** [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU|Xen DomU (paravirtualized)]]
** [[Xen LiveCD]]
** [[Xen PCI Passthrough]]
** [[K8s]] Building a K8s Kubernetes Cluster on Alpine Linux
* [[Runc]]

== [[Simple_Walkthrough]] ==
* [[About-virtualization-simple]]
* [[LXC_Alpinelinux_Simple]]
* [[Qemu-simple]]

== Tutorials ==

* [[TTY_Autologin|TTY Autologin]]
* [[Kexec|Faster rebooting with kexec]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small Office Services]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Linux iSCSI Target (TCM)]]
* [[ISP Mail Server 3.x HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-service ISP mail server)''
* [[Grommunio Mail Server]] ''(Mariadb+Postfix+Rspamd+Grommunio - Full-service mail server as MS exchange replacement)''
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[Streaming Security Camera Video with VLC]]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
* [[Compile software from source|How to Compile a software from source in Alpine Linux]]
* [https://ww2.coastal.edu/mmurphy2/oer/alpine/ Alpine Linux tutorials - Dr Murphy, Computing Science Associate Professor]
* [[Michael's base installation procedure|Michael's base installation procedure]]
* [[Michael's cwm desktop (minimal)|Michael's cwm desktop (minimal)]]
* [[Michael's sway desktop (minimal)|Michael's Sway desktop (minimal)]]
* [[Sway_customization_guide|Sway customization guide]] ''(Tutorial re Sway config file basics)''
* [[Using Distrobox For VR Gaming|Using Distrobox For VR Gaming]]

Alpine Package Keeper

2026-02-19T07:39:33Z

Prabuanand: removed some repetitions to reduce the content

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |Miscellaneous
|-
|[[#apk audit|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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk audit ==

The audit applet examines the system or specified directories for changes compared to the package database. The purpose of audit is to detect unauthorized modifications or to identify files/paths to [[Alpine_local_backup#Include_special_files/folders_to_the_apkovl|include them in apkovl]].

These flags determine the '''scope''' of the audit i.e which files are examined:
--backup (Default): Files flagged as configuration/protected
--system: Files provided by packages but ignores new/untracked files and configuration files.
--full: All package tracked files and all newly added files/directories.

When the audit exits with code 99 but produces no output, change the scope and re-run the audit with option --full --details to reveal the output.

The following flags modify the output and provide additional information:
--details: Shows the exact metadata differences using + and - symbols.
--check-permissions: Includes UID, GID, and Mode in the comparison.
--packages: Prints only the packages with changed files.

The packages flag is useful to repair all packages with modified files, by using the command:{{Cmd|<nowiki># apk audit --packages -q | xargs apk fix</nowiki>}}

By default, the output format is one file per line, for each modified file. A character is printed indicating the line type, followed by a space, then either the affected path or the metadata details. The metadata details appear above the relevant file/path.

An optional <path> can be added to limit the audit to a specific directory. The example output below illustrates most of the options explained above.

<pre>
# chmod 777 /etc/init.d/networking
# apk audit --check-permissions --details /etc/init.d/networking
# echo $?
99
# apk audit --check-permissions --details --full |grep -C 3 networking
- mode=755 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
+ mode=777 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
M etc/init.d/networking
# apk fix openrc
# apk audit --check-permissions --details --full |grep -C 3 networking
# echo $?
1
</pre>

The following table summarizes the changes detected and displayed by the audit command.

{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Audit command output
|-
| - || Details as per Database record (shown only with --details flag)
|-
| + || Details as per On-disk record (shown only with --details flag)
|-
| A || File added
|-
| d || Directory added
|-
| D || Directory added (with non-listed files/subdirs)
|-
| e || error occured during audit (e.g. no permissions to read file)
|-
| M || File metadata changed (uid, gid, or mode)
|-
| m || Directory metadata changed
|-
| U || File contents modified
|-
| X || File deleted
|-
| x || xattrs changed
|-
|}

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. 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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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}}.

=== Huh? Error reporter did not find the broken constraints===

<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#World|world]] file and appears when [[Upgrading Alpine Linux to a new release branch]]. When apk-tools solver returns above message, that is always a bug. Please file a bug report [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues here].

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for an example on how this error was temporarily resolved.

=== Issues due to /usr merge ===

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, for users who have migrated to the [[Repositories#Message_on_/usr_merge|merged /usr]], there are certain known issues like {{Issue|17624|apk audit does not work}}.


==== ERROR:Could not find owner package ====

The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[[Repositories#Message_on_/usr_merge|/usr merge]]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

In order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-19T07:30:46Z

Prabuanand: moved the exit code section and added wikilink

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |Miscellaneous
|-
|[[#apk audit|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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk audit ==

The audit applet audits the system or specified directories for changes compared to the package database. The default option is to audit configuration files only. Options are available to audit all system files or to audit specified directories to detect unauthorized modifications or to identify files/paths to [[Alpine_local_backup#Include_special_files/folders_to_the_apkovl|include them in apkovl]].

These flags determine which files audit applet will examine i.e '''scope''' of the audit.
--backup (Default): Files flagged as configuration/protected
--system: Files provided by packages but ignores new/untracked files and configuration files.
--full: All package tracked files and all newly added files/directories.

When the audit exits with code 99 but produces no output,change the scope and re-run the audit with option --full --details to reveal the output.

The following flags modify the output and provide additional information:
--details: Shows the exact metadata differences using + and - symbols.
--check-permissions: Includes UID, GID, and Mode in the comparison.
--packages: Prints only the packages with changed files.

The packages flag is useful to repair all packages with modified files, by using the command:{{Cmd|<nowiki># apk audit --packages -q | xargs apk fix</nowiki>}}

By default, the output format is one file per line, for each modified file. A character is printed indicating the line type, followed by a space, then either the affected path or the metadata details. The metadata details usually appears above the relevant file/path.

An optional <path> can be added to limit the audit to a specific directory. The example output below illustrates most of the options explained above.

<pre>
# chmod 777 /etc/init.d/networking
# apk audit --check-permissions --details /etc/init.d/networking
# echo $?
99
# apk audit --check-permissions --details --full |grep -C 3 networking
- mode=755 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
+ mode=777 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
M etc/init.d/networking
# apk fix openrc
# apk audit --check-permissions --details --full |grep -C 3 networking
# echo $?
1
</pre>

The following table summarizes the changes detected and displayed by the audit command.

{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Audit command output
|-
| - || Details as per Database record (shown only with --details flag)
|-
| + || Details as per On-disk record (shown only with --details flag)
|-
| A || File added
|-
| d || Directory added
|-
| D || Directory added (with non-listed files/subdirs)
|-
| e || error occured during audit (e.g. no permissions to read file)
|-
| M || File metadata changed (uid, gid, or mode)
|-
| m || Directory metadata changed
|-
| U || File contents modified
|-
| X || File deleted
|-
| x || xattrs changed
|-
|}

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. 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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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}}.

=== Huh? Error reporter did not find the broken constraints===

<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#World|world]] file and appears when [[Upgrading Alpine Linux to a new release branch]]. When apk-tools solver returns above message, that is always a bug. Please file a bug report [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues here].

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for an example on how this error was temporarily resolved.

=== Issues due to /usr merge ===

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, for users who have migrated to the [[Repositories#Message_on_/usr_merge|merged /usr]], there are certain known issues like {{Issue|17624|apk audit does not work}}.


==== ERROR:Could not find owner package ====

The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[[Repositories#Message_on_/usr_merge|/usr merge]]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

In order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-19T07:04:51Z

Prabuanand: clarified on the scope of the audit as this word is not part of the man page

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk audit ==

The audit applet audits the system or specified directories for changes compared to the package database. The default option is to audit configuration files only. Options are available to audit all system files or to audit specified directories to detect unauthorized modifications or to identify files/paths to [[Alpine_local_backup#Include_special_files/folders_to_the_apkovl|include them in apkovl]].

These flags determine which files audit applet will examine i.e '''scope''' of the audit.
--backup (Default): Files flagged as configuration/protected
--system: Files provided by packages but ignores new/untracked files and configuration files.
--full: All package tracked files and all newly added files/directories.

The following flags modify the output and provide additional information:
--details: Shows the exact metadata differences using + and - symbols.
--check-permissions: Includes UID, GID, and Mode in the comparison.
--packages: Prints only the packages with changed files.

The packages flag is useful to repair all packages with modified files, by using the command:{{Cmd|<nowiki># apk audit --packages -q | xargs apk fix</nowiki>}}

By default, the output format is one file per line, for each modified file. A character is printed indicating the line type, followed by a space, then either the affected path or the metadata details. The metadata details usually appears above the relevant file/path.

Exit Codes are affected by the scope:
1 (or 0): Audit completed and found no discrepancies
99: The audit found discrepancies, but not printed.

For exit code 99 with no output, change the scope and re-run the audit with options like --full --details.

An optional <path> can be added to limit the audit to a specific directory. The example output below illustrates most of the options explained above.

<pre>
# chmod 777 /etc/init.d/networking
# apk audit --check-permissions --details /etc/init.d/networking
# echo $?
99
# apk audit --check-permissions --details --full |grep -C 3 networking
- mode=755 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
+ mode=777 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
M etc/init.d/networking
# apk fix openrc
# apk audit --check-permissions --details --full |grep -C 3 networking
# echo $?
1
</pre>

The following table summarizes the changes detected and displayed by the audit command.

{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Audit command output
|-
| - || Details as per Database record (shown only with --details flag)
|-
| + || Details as per On-disk record (shown only with --details flag)
|-
| A || File added
|-
| d || Directory added
|-
| D || Directory added (with non-listed files/subdirs)
|-
| e || error occured during audit (e.g. no permissions to read file)
|-
| M || File metadata changed (uid, gid, or mode)
|-
| m || Directory metadata changed
|-
| U || File contents modified
|-
| X || File deleted
|-
| x || xattrs changed
|-
|}

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. 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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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}}.

=== Huh? Error reporter did not find the broken constraints===

<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#World|world]] file and appears when [[Upgrading Alpine Linux to a new release branch]]. When apk-tools solver returns above message, that is always a bug. Please file a bug report [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues here].

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for an example on how this error was temporarily resolved.

=== Issues due to /usr merge ===

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, for users who have migrated to the [[Repositories#Message_on_/usr_merge|merged /usr]], there are certain known issues like {{Issue|17624|apk audit does not work}}.


==== ERROR:Could not find owner package ====

The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[[Repositories#Message_on_/usr_merge|/usr merge]]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

In order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-19T06:45:05Z

Prabuanand: added example along with explanations

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk audit ==

The audit applet audits the system or specified directories for changes compared to the package database. The default option is to audit configuration files only. Options are available to audit all system files or to audit specified directories to detect unauthorized modifications or to identify files/paths to [[Alpine_local_backup#Include_special_files/folders_to_the_apkovl|include them in apkovl]].

These flags determine which files audit applet will examine.
--backup (Default): Only audits files flagged as configuration/protected (those listed in protected_paths.d).
--system: Audits all files provided by packages (integrity check) but ignores new/untracked files and skips configuration files.
--full: The most comprehensive scan. Use this option to audit all package tracked files and to report all newly added files/directories.

Exit Codes:
Exit Code 1 (or 0): The audit completed and found no discrepancies within the specified scope.
Exit Code 99: The audit found discrepancies, but they are not being printed because they fall outside the current filter (e.g., a system file was modified but you didn't use --full). If you see 99 with no output, re-run with --full --details.

The following flags modify the output and provide additional information:
--details: Shows the exact metadata differences using + and - symbols.
--check-permissions: Includes UID, GID, and Mode in the comparison.
--packages: Prints only the packages with changed files.

The packages flag is useful to repair all packages with modified files, by using the command:{{Cmd|<nowiki># apk audit --packages -q | xargs apk fix</nowiki>}}

By default, the output format is one file per line, for each modified file. A character is printed indicating the line type, followed by a space, then either the affected path or the metadata details. The metadata details usually appears above the relevant file/path.

An optional <path> can be added to limit the audit to a specific directory in all the above cases as can be seen in the example output below.

<pre>
# chmod 777 /etc/init.d/networking
# apk audit --check-permissions --details /etc/init.d/networking
# echo $?
99
# apk audit --check-permissions --details --full |grep -C 3 networking
- mode=755 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
+ mode=777 uid=0 gid=0 hash=9fe622bd6d06ed19eb53c1a665343b98f864c5cd
M etc/init.d/networking
# apk fix openrc
# apk audit --check-permissions --details --full |grep -C 3 networking
# echo $?
1
</pre>

The following table summarizes the changes detected and displayed by the audit command.

{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Audit command output
|-
| - || Details as per Database record (shown only with --details flag)
|-
| + || Details as per On-disk record (shown only with --details flag)
|-
| A || File added
|-
| d || Directory added
|-
| D || Directory added (with non-listed files/subdirs)
|-
| e || error occured during audit (e.g. no permissions to read file)
|-
| M || File metadata changed (uid, gid, or mode)
|-
| m || Directory metadata changed
|-
| U || File contents modified
|-
| X || File deleted
|-
| x || xattrs changed
|-
|}

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. 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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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}}.

=== Huh? Error reporter did not find the broken constraints===

<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#World|world]] file and appears when [[Upgrading Alpine Linux to a new release branch]]. When apk-tools solver returns above message, that is always a bug. Please file a bug report [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues here].

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for an example on how this error was temporarily resolved.

=== Issues due to /usr merge ===

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, for users who have migrated to the [[Repositories#Message_on_/usr_merge|merged /usr]], there are certain known issues like {{Issue|17624|apk audit does not work}}.


==== ERROR:Could not find owner package ====

The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[[Repositories#Message_on_/usr_merge|/usr merge]]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

In order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Talk:Alpine Package Keeper

2026-02-19T04:14:47Z

Prabuanand: added explanation on why the content was moved

== note on apk update ==

There is an --update-cache or -U option which can be used together with ''apk <anything>'' that will first perform an ''apk update''. Might be worth mentioning that. --[[User:Ncopa|Ncopa]] 11:02, 16 August 2010 (UTC)

There is an --initdb option that does not even show in apk help command. Is this deprecated ? --[[User:Vkrishn|Vkrishn]] ([[User talk:Vkrishn|talk]]) 10:32, 2 May 2013 (UTC)

== "Packages and Repositories" section - ftp still being used? ==

The stated section currently has the following example of a valid repo:
<nowiki>ftp://dl-3.alpinelinux.org/alpine/v2.6/main</nowiki>
Is the '''ftp''' protocol still being used?
The passage could then be updated to "v3.7".
--[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 22:43, 19 January 2018 (UTC)

== Troubleshooting - "apk-tools is old" ==

Could the following instruction be added? This may not yet have been tested on a system that is still exhibiting this error message:

If edge is not tagged, upgrade from one of the edge/main mirrors. For example:

<pre>sudo apk add --upgrade apk-tools --update-cache --repository http://dl-2.alpinelinux.org/alpine/edge/main/ --allow-untrusted</pre>

--[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:58, 1 February 2018 (UTC)

== How to use the --virtual parameter ==

As a new user trying to keep a docker image small but needing to compile some packages, it would be very, very helpful to include a detailed explanation of the `--virtual` parameter of `add` with examples of how to use it. I would add it myself but I only know what I've read in stackoverflow and, well, you know how reliable that can be… TIA

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Tedsecretsource|Tedsecretsource]] ([[User talk:Tedsecretsource|{{int:talkpagelinktext}}]] • [[Special:Contributions/Tedsecretsource|{{int:contribslink}}]]) 08:45, 22 January 2023‎

== .boot_repository in package cache ==

It seems like the advice about using .boot_repository with the cache directory doesn't work, since a repository requires an APKINDEX.tar.gz file but the cache has APKINDEX.f00bar.tar.gz files. Should the article be changed, or is this a bug?
[[User:Dklr433|Dklr433]] ([[User talk:Dklr433|talk]]) 20:01, 4 March 2024 (UTC)

== Repository pinning==

I found the below section in a [https://wiki.alpinelinux.org/w/index.php?title=Alpine_Package_Keeper&oldid=26240#Repository_pinning older version] of this page. But after reading the [https://github.com/alpinelinux/apk-tools/blob/master/doc/apk-world.5.scd manual], i believe the information is wrong. The current content appears as [[Repositories#Tagged repository|tagged repository]]. Can someone please confirm, if my understanding/changes are correct.
----
You can specify additional "tagged" repositories {{Cat|/etc/apk/repositories|...
@personal https:/personal-repo.example.com/alpine-apks/}}
After which you can "pin" dependencies to these tags using: {{ic|apk add application@personal}}
apk will by default only use the untagged repositories, but adding a package with a @tag:
1. will prefer the repository with that tag for the named package, even if a later version of the package is available in another repository
2. ''allows'' pulling in dependencies for the tagged package from the tagged repository (though it ''prefers'' to use untagged repositories to satisfy dependencies if possible)
---- [[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 05:32, 24 March 2025 (UTC)

== Issues due to /usr merge==

Dear [[User:John3-16|John3-16]], I have moved the content added by you to a seperate section titled [[Alpine_Package_Keeper#Issues_due_to_/usr_merge|Issues due to /usr merge]] under troubleshooting. Since the /usr merge has been paused as of now and affects only migrated users, let this be kept in a seperate section, so it is easier to remove at a future date, once all related issues are resolved. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 04:14, 19 February 2026 (UTC)

Alpine Package Keeper

2026-02-19T04:04:01Z

Prabuanand: moved the error related to info command to troubleshooting section and added apk audit

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk audit ==

The audit applet audits the system or specified directories for changes compared to the package database. The default option is to audit configuration files only. Options are available to audit all system files or to audit specified directories and files or packages.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. 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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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}}.

=== Huh? Error reporter did not find the broken constraints===

<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#World|world]] file and appears when [[Upgrading Alpine Linux to a new release branch]]. When apk-tools solver returns above message, that is always a bug. Please file a bug report [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues here].

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for an example on how this error was temporarily resolved.

=== Issues due to /usr merge ===

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, for users who have migrated to the [[Repositories#Message_on_/usr_merge|merged /usr]], there are certain known issues like {{Issue|17624|apk audit does not work}}.


==== ERROR:Could not find owner package ====

The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[[Repositories#Message_on_/usr_merge|/usr merge]]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

In order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-18T13:12:42Z

Prabuanand: added note to file a bug

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

{{Note|The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[https://wiki.alpinelinux.org/wiki/Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge /usr merge]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, in order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}
}}

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

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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}}.

=== Huh? Error reporter did not find the broken constraints===

<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#World|world]] file and appears when [[Upgrading Alpine Linux to a new release branch]]. When apk-tools solver returns above message, that is always a bug. Please file a bug report [https://gitlab.alpinelinux.org/alpine/apk-tools/-/issues here].

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for an example on how this error was temporarily resolved.

== See also ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-18T06:44:12Z

Prabuanand: fixed typo

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

{{Note|The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[https://wiki.alpinelinux.org/wiki/Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge /usr merge]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, in order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}
}}

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

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

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

=== Huh? Error reporter did not find the broken constraints===

When [[Upgrading Alpine Linux to a new release branch]] you may receive the below message:
<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#World|world]] file.

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for more information.

=== 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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-18T06:18:25Z

Prabuanand: added warning about alpine-base

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

{{Warning|When manually editing world file, do not remove the meta package entry '''alpine-base''' or other important entries like '''linux-*''' etc. Doing so may render the system unbootable.}}

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning|The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

{{Note|The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[https://wiki.alpinelinux.org/wiki/Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge /usr merge]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, in order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}
}}

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

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

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

=== Huh? Error reporter did not find the broken constraints===

When [[Upgrading Alpine Linux to a new release branch]] you may receive the below message:
<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#world|world]] file.

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for more information.

=== 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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-18T05:59:08Z

Prabuanand: /* Huh? Error reporter did not find the broken constraints. */

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

{{Note|The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[https://wiki.alpinelinux.org/wiki/Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge /usr merge]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, in order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}
}}

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

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

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

=== Huh? Error reporter did not find the broken constraints===

When [[Upgrading Alpine Linux to a new release branch]] you may receive the below message:
<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#world|world]] file.

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for more information.

=== 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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-18T05:58:53Z

Prabuanand: added error message based on IRC discussion

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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 when used with the {{ic|--who-owns}} option, or simply {{ic|-W}}. For example: {{cmd|$ apk info --who-owns /sbin/lbu}}
will display
<pre>
/sbin/lbu is owned by alpine-conf-x.x-rx
</pre>

{{Note|The {{ic|apk info --who-owns}} command is currently subject to requiring the declaration of a file's path to be updated in the case where '''[https://wiki.alpinelinux.org/wiki/Upgrading_Alpine_Linux_to_a_new_release_branch#Upgrading_to_Edge /usr merge]''' had been previously applied and where, additionally, the file was originally assigned to paths under {{Path|/lib}}, {{Path|/bin}} or {{Path|/sbin}}. Otherwise, an error is returned, seeing how these are now soft-linked into {{Path|/usr}}:

<pre>
$ apk info --who-owns /sbin/lbu
ERROR: /sbin/lbu: Could not find owner package
</pre>

Further to the [https://alpinelinux.org/posts/2025-10-01-usr-merge.html /usr merge] announcement, in order for this facility to function in such cases, {{Path|/usr}} currently needs to be prepended to the declaration of the path for all such files, seeing how those files are now soft-linked to {{Path|/usr/lib}}, {{Path|/usr/bin}} or {{Path|/usr/sbin}}: {{cmd|$ apk info --who-owns /usr/sbin/lbu}}
}}

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

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

However, if the currently installed '''''version''''' of the package (say, <var>foo</var> version <var>1.2.3-r4</var>) is no longer available in the operating system's repositories (i.e. the repos specified in {{Path|/etc/apk/repositories}}) following the latest system update, then '''apk fix''' will not fix the package and will report ''"[APK unavailable, skipped]"'' instead:

{{Cmd|$ doas apk fix <var>foo</var>
(1/1) [APK unavailable, skipped] Reinstalling foo (1.2.3-r4)}}

This outcome applies both with '''apk v3''' and '''v2''', and includes cases where either a higher or lower version of the package is found in the employed repos. In such cases where a different version exists, consider replacing the package using the [[Alpine_Package_Keeper#Add_a_local_Package|{{ic|apk upgrade --available}}]] command, which will either upgrade or downgrade ''all packages'' to the versions currently offered.

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

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

=== Huh? Error reporter did not find the broken constraints.===

When [[Upgrading Alpine Linux to a new release branch]] you may receive the below message:
<Pre>
ERROR: unable to select packages:
Huh? Error reporter did not find the broken constraints.
</Pre>

The above message can be due to version conflicts caused by a software package present in the [[#world|world]] file.

To identify the offending software package, take a backup of the world file, then take stuff out of world until the upgrade works. Or alternatively, begin with a minimal version of world file and add things until it breaks again.

Once the upgrade is done, you may be able to add back the offending software package, if supported in the newer version.

Check the [https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log IRC logs] dated 2026-02-18 for more information.

=== 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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-17T09:57:06Z

Prabuanand: add wikitag

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> command:
{{Cmd|<nowiki>$ apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr</nowiki>}}

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-17T09:53:17Z

Prabuanand: replaced the command with a simpler alternative

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> commands.

<pre>
apk --installed query --format json --fields name,installed-size '*'|jq -r '.[] | [."installed-size", ."name"] | @tsv' | sort -nr
</pre>

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-02-17T07:12:16Z

Prabuanand: based on irc discusion on 2026-02-17 - https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

=== List packages by installed size ===
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk query}}
The below command lists all installed packages by installed size. It requires {{pkg|jq}} package and uses [[#apk query|query]] option. Use the below command with <Code>less</Code> or <Code>head</Code> commands.

<pre>
apk query --installed --format json --fields name,installed-size '*' | jq -r '.[] | (.["installed-size"] // 0) as $s | (if $s >= 1048576 then "\($s/1048576|round) MB" elif $s > 0 then "\($s/1024|round) KB" else "0 B" end) as $f | "\($s)\t\($f)\t\(.name)"' | sort -nr | cut -f2- | expand -t 15
</pre>

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

System Disk Mode

2026-02-13T18:00:55Z

Prabuanand: fixed wikitag as per Help:Editing page and added wikilink

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to Reboot the Computer.

If the fsck Command does Fix the Corruption on the Root File System but the '''Error: Mounting Root Failed''' still persists then the next step would be to ReBuild the '''initramfs''' File System with the '''mkinitfs''' Command then Reboot. You need to '''Mount the Root Partition''' and [[Chroot]] into the Mounted Root Partition before running the mkinitfs Command as shown in the [[Initramfs init|initramfs]] page.

==== Check File System Kernel Modules are Loading ====

Run the below command to output the File System Kernel modules, where the file system can be one among the following: '''ext2''', '''ext3''', '''ext4''', '''btrfs''', '''xfs''', '''fat''':

{{Cmd|<nowiki># lsmod | grep <File System></nowiki>}}

An example output is given below for the above command, with necessary abbreviations explained:

<Pre>
alpinepc:~# lsmod | grep ext4

ext4 1155072 2
crc16 12288 1 ext4
mbcache 16384 1 ext4
jbd2 200704 1 ext4
</Pre>
EXT4 = [[Filesystems|File System]] 
CRC16 = EXT4 Compression Support 
MBCACHE = MetaData Cache 
JBD2 = Journaling 

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

Bootloaders

2026-02-12T04:14:34Z

Prabuanand: added limine and moved grub and refind as refind is still in testing repository as of 3.23

A ''bootloader'' is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a ''boot manager''. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.

The following bootloaders are available in Alpine Linux:-

* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux when booting the Alpine Installer ISO. It is also the bootloader when creating a Live USB/CD/ISOLinux/PXELinux. Supports the Filesystems: FAT12/16/32
* <code>[[#Extlinux|Extlinux]]</code> is the default lightweight bootloader used in Alpine Linux when Installing the Alpine OS to Disk via BIOS/Legacy Boot. Supports the Filesystems: EXT2/3/4, BTRFS, XFS 
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader used in Alpine Linux when Installing the Alpine OS to Disk via UEFI.
* <code>[[#Limine|Limine]]</code> is a modern, advanced, portable, multiprotocol bootloader and boot manager.
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader.
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems. 
* [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.

A [[#Using a UKI|Unified Kernel Image (UKI)]] is additionally supported, available for UEFI only. It is a UEFI executable that can be useful in [https://uapi-group.org/specifications/specs/unified_kernel_image/ certain use cases], including secure boot, clouds and containers.

Note that {{pkg|gummiboot}} is a ''deprecated'' UEFI boot manager that was originally able to leverage UEFI firmware and detect bootable images such as Linux kernels that have an EFI stub on the EFI System Partition (ESP). The [https://cgit.freedesktop.org/gummiboot/ gummiboot project] was discontinued in 2015 and renamed as {{Pkg|systemd-boot}} for systemd systems and is only available in Alpine Linux in the [[Repositories#Testing|testing repository]]. As it had no runtime dependencies, '''gummiboot''' was appreciated for its simplicity as a lightweight, minimal UEFI boot solution. Its UEFI stub, {{pkg|gummiboot-efistub}}, was used [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|to generate a Unified Kernel Images (UKIs)]] e.g. for [[DM-verity]] and Secure Boot, but [[Release_Notes_for_Alpine_3.22.0#Secure_Boot_and_Gummiboot|it has been deprecated since Alpine Linux 3.22]] and is no longer maintained; it has been replaced by '''systemd-efistub''' (note that the latter package [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|only supplies EFI stub binaries]] and doesn’t depend on any systemd components).

== Syslinux ==

If you want to switch from another bootloader back to ''Syslinux'', or if for some reason you want to install Syslinux manually, then the following steps are required.

Install the {{pkg|syslinux}} package:

{{cmd|# apk add syslinux}}

If you're using GPT partitions, then install the ''GPT MBR'' onto the drive that you want to install the bootloader on (in this case, {{path|/dev/sda}}):

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}

Or, if you're using DOS partitions, then install the ''DOS MBR'' instead:

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}


Next, install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS and UFS/FFS filesystems.

{{cmd|# syslinux --install /boot}}

The configuration file is located in {{path|/boot/syslinux/syslinux.cfg}}.

Alpine Linux ships with a script, <code>update-extlinux</code>, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.

You can also edit and add additional menu entries in the bootloader configuration file for dual booting multiple os's: {{path|/boot/syslinux/syslinux.cfg}}

=== Using EFI with syslinux ===

The Alpine Linux installer automatically uses [[#GRUB|GRUB]] if EFI mode is detected. The section below is specifically about using EFI with Syslinux.

Assuming that {{path|/mnt}} is a FAT32 partition of type EF00 and that {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:

{{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
# cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
# cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
# cp /boot/vmlinuz* /mnt/EFI/syslinux/
# cp /boot/initramfs* /mnt/EFI/syslinux/
</nowiki>}}

You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).

In the end, the {{path|/mnt/EFI/syslinux/syslinux.cfg}} file should look like this:

{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
DEFAULT menu.c32
PROMPT 0
MENU TITLE Alpine/Linux Boot Menu
MENU HIDDEN
MENU AUTOBOOT Alpine will be booted automatically in # seconds
TIMEOUT 10
LABEL lts
MENU DEFAULT
MENU LABEL Linux lts
LINUX /vmlinuz-lts
INITRD /initrd-lts
APPEND root=/dev/sda3 modules=sd-mod,usb-storage,ext4 quiet
</nowiki>}}

Finally, add <code>syslinux</code> to the EFI boot menu. Assuming that {{path|/dev/sda}} is your hard drive —'''''be careful to check first what is its path on your device and to adjust accordingly''''':

{{cmd|<nowiki># apk add efibootmgr
# efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
</nowiki>}}

You can now verify that the boot entry has been added:

'''efibootmgr'''
<pre>
BootCurrent: 0001
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
</pre>

== GRUB ==

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}

For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI-compatible filesystem, such as FAT32.

{{cmd|# apk add grub-efi efibootmgr}}

Next, install the MBR and GRUB binaries to disk for BIOS mode:

{{cmd|# grub-install /dev/vda}}

For EFI mode:

{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}

Then, add this line to {{path|/etc/default/grub}}:

{{cat|/etc/default/grub|<nowiki># GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"</nowiki>}}

GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:

{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

This script can be configured via the {{path|/etc/default/grub}} file.

If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].

Consult [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html gnu.org's online manual] for a list of available <code>grub-mkconfig</code> configuration options.

== Limine ==

[https://codeberg.org/Limine/Limine Limine] is a modern, advanced, portable, multiprotocol bootloader and boot manager, also used as the reference implementation for the Limine boot protocol. It supports partitioning schemes like MBR, GPT and Unpartitioned media.

== EFI Boot Stub ==

To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with ''efibootmgr''.

=== efibootmgr ===

Install {{Pkg|efibootmgr}}:
{{cmd|# apk add efibootmgr}}

Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.

{{cat|add-bootentry|<nowiki>#!/bin/sh

params="root=/dev/sdXZ rootfstype=ext4 rw \
initrd=\intel-ucode.img \
initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
--disk /dev/sdX --part Y \
--loader /vmlinuz-lts \
--unicode "${params}" \
--verbose
</nowiki>}}

Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-stable}}, then replace <code>lts</code> with <code>stable</code> in the script.

{{Tip|If you're modifying EFI records from a running system (e. g. migrating from GRUB), you can populate {{ic|$params}} from {{ic|/proc/cmdline}}. Make sure to append {{ic|initrd}} param if it's missing since GRUB does not add it to the command line.}}

{{Note| The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
}}

Optionally, set the newly-created entry as the default:

{{cmd|# efibootmgr -n XXXX}}

Where <code>XXXX</code> is the boot number of the new entry.

{{Note| The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update <code>fstab</code> to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}. }}

== rEFInd ==
{{Main|rEFInd}}

[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.
== Using a UKI ==

'''[https://github.com/uapi-group/specifications/blob/main/specs/unified_kernel_image.md#unified-kernel-image-uki Unified Kernel Image]''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.

The [[UEFI Secure Boot]] page contains the instructions for setting up an a UKI. While this is typically done in order to ''SecureBoot'', it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.

Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}} :

{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the stable kernel, install the UKI into the default UEFI path.
if [ "$1" == "stable" ]; then
output_dir="/efi/EFI/Boot/"
output_name="bootx64.efi"
fi
</nowiki>}}

{{Note| {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures, the exact name will vary.}}

== Troubleshooting ==

Since bootloaders are installed only during [[System Disk Mode]], the errors related to them are documented in [[System Disk Mode#Troubleshooting|that page]].

== See also ==
* [[Enable Serial Console on Boot]]
* [[Silent boot]]
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki - Bootloaders]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki - Boot loader]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki - Bootloaders]
* [https://docs.u-boot.org/en/latest/develop/release_cycle.html u-boot.org docs - U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

Bootloaders

2026-02-10T15:17:22Z

Prabuanand: fixed typo

A ''bootloader'' is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a ''boot manager''. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.

The following bootloaders are available in Alpine Linux:-

* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux. 
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems. 
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader. 
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader. 
* [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.

A [[#Using a UKI|Unified Kernel Image (UKI)]] is additionally supported, available for UEFI only. It is a UEFI executable that can be useful in [https://uapi-group.org/specifications/specs/unified_kernel_image/ certain use cases], including secure boot, clouds and containers.

Note that {{pkg|gummiboot}} is a ''deprecated'' UEFI boot manager that was originally able to leverage UEFI firmware and detect bootable images such as Linux kernels that have an EFI stub on the EFI System Partition (ESP). The [https://cgit.freedesktop.org/gummiboot/ gummiboot project] was discontinued in 2015 and renamed as {{Pkg|systemd-boot}} for systemd systems and is only available in Alpine Linux in the [[Repositories#Testing|testing repository]]. As it had no runtime dependencies, '''gummiboot''' was appreciated for its simplicity as a lightweight, minimal UEFI boot solution. Its UEFI stub, {{pkg|gummiboot-efistub}}, was used [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|to generate a Unified Kernel Images (UKIs)]] e.g. for [[DM-verity]] and Secure Boot, but [[Release_Notes_for_Alpine_3.22.0#Secure_Boot_and_Gummiboot|it has been deprecated since Alpine Linux 3.22]] and is no longer maintained; it has been replaced by '''systemd-efistub''' (note that the latter package [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|only supplies EFI stub binaries]] and doesn’t depend on any systemd components).

== Syslinux ==

If you want to switch from another bootloader back to ''Syslinux'', or if for some reason you want to install Syslinux manually, then the following steps are required.

Install the {{pkg|syslinux}} package:

{{cmd|# apk add syslinux}}

If you're using GPT partitions, then install the ''GPT MBR'' onto the drive that you want to install the bootloader on (in this case, {{path|/dev/sda}}):

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}

Or, if you're using DOS partitions, then install the ''DOS MBR'' instead:

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}


Next, install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS and UFS/FFS filesystems.

{{cmd|# extlinux --install /boot}}

The configuration file is located in {{path|/boot/extlinux.conf}}.

Alpine Linux ships with a script, <code>update-extlinux</code>, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.

You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory e.g. for dual booting.

=== Using EFI with syslinux ===

The Alpine Linux installer automatically uses [[#GRUB|GRUB]] if EFI mode is detected. The section below is specifically about using EFI with Syslinux.

Assuming that {{path|/mnt}} is a FAT32 partition of type EF00 and that {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:

{{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
# cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
# cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
# cp /boot/vmlinuz* /mnt/EFI/syslinux/
# cp /boot/initramfs* /mnt/EFI/syslinux/
</nowiki>}}

You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).

In the end, the {{path|/mnt/EFI/syslinux/syslinux.cfg}} file should look like this:

{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
DEFAULT menu.c32
PROMPT 0
MENU TITLE Alpine/Linux Boot Menu
MENU HIDDEN
MENU AUTOBOOT Alpine will be booted automatically in # seconds
TIMEOUT 10
LABEL lts
MENU DEFAULT
MENU LABEL Linux lts
LINUX /vmlinuz-lts
INITRD /initrd-lts
APPEND root=/dev/sda3 modules=sd-mod,usb-storage,ext4 quiet
</nowiki>}}

Finally, add <code>syslinux</code> to the EFI boot menu. Assuming that {{path|/dev/sda}} is your hard drive —'''''be careful to check first what is its path on your device and to adjust accordingly''''':

{{cmd|<nowiki># apk add efibootmgr
# efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
</nowiki>}}

You can now verify that the boot entry has been added:

'''efibootmgr'''
<pre>
BootCurrent: 0001
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
</pre>

== rEFInd ==
{{Main|rEFInd}}

[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.

== GRUB ==

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}

For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI-compatible filesystem, such as FAT32.

{{cmd|# apk add grub-efi efibootmgr}}

Next, install the MBR and GRUB binaries to disk for BIOS mode:

{{cmd|# grub-install /dev/vda}}

For EFI mode:

{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}

Then, add this line to {{path|/etc/default/grub}}:

{{cat|/etc/default/grub|<nowiki># GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"</nowiki>}}

GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:

{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

This script can be configured via the {{path|/etc/default/grub}} file.

If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].

Consult [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html gnu.org's online manual] for a list of available <code>grub-mkconfig</code> configuration options.

== EFI Boot Stub ==

To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with ''efibootmgr''.

=== efibootmgr ===

Install {{Pkg|efibootmgr}}:
{{cmd|# apk add efibootmgr}}

Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.

{{cat|add-bootentry|<nowiki>#!/bin/sh

params="root=/dev/sdXZ rootfstype=ext4 rw \
initrd=\intel-ucode.img \
initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
--disk /dev/sdX --part Y \
--loader /vmlinuz-lts \
--unicode "${params}" \
--verbose
</nowiki>}}

Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-stable}}, then replace <code>lts</code> with <code>stable</code> in the script.

{{Tip|If you're modifying EFI records from a running system (e. g. migrating from GRUB), you can populate {{ic|$params}} from {{ic|/proc/cmdline}}. Make sure to append {{ic|initrd}} param if it's missing since GRUB does not add it to the command line.}}

{{Note| The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
}}

Optionally, set the newly-created entry as the default:

{{cmd|# efibootmgr -n XXXX}}

Where <code>XXXX</code> is the boot number of the new entry.

{{Note| The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update <code>fstab</code> to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}. }}

== Using a UKI ==

'''[https://github.com/uapi-group/specifications/blob/main/specs/unified_kernel_image.md#unified-kernel-image-uki Unified Kernel Image]''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.

The [[UEFI Secure Boot]] page contains the instructions for setting up an a UKI. While this is typically done in order to ''SecureBoot'', it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.

Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}} :

{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the stable kernel, install the UKI into the default UEFI path.
if [ "$1" == "stable" ]; then
output_dir="/efi/EFI/Boot/"
output_name="bootx64.efi"
fi
</nowiki>}}

{{Note| {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures, the exact name will vary.}}

== Troubleshooting ==

Since bootloaders are installed only during [[System Disk Mode]], the errors related to them are documented in [[System Disk Mode#Troubleshooting|that page]].

== See also ==
* [[Enable Serial Console on Boot]]
* [[Silent boot]]
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki - Bootloaders]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki - Boot loader]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki - Bootloaders]
* [https://docs.u-boot.org/en/latest/develop/release_cycle.html u-boot.org docs - U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

Bootloaders

2026-02-10T14:46:18Z

Prabuanand: added wikilink

A ''bootloader'' is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a ''boot manager''. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.

The following bootloaders are available in Alpine Linux:-

* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux. 
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems. 
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader. 
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader. 
* [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.

A [[#Using a UKI|Unified Kernel Image (UKI)]] is additionally supported, available for UEFI only. It is a UEFI executable that can be useful in [https://uapi-group.org/specifications/specs/unified_kernel_image/ certain use cases], including secure boot, clouds and containers.

Note that {{pkg|gummiboot}} is a ''deprecated'' UEFI boot manager that was originally able to leverage UEFI firmware and detect bootable images such as Linux kernels that have an EFI stub on the EFI System Partition (ESP). The [https://cgit.freedesktop.org/gummiboot/ gummiboot project] was discontinued in 2015 and renamed as {{Pkg|systemd-boot}} for systemd systems and is only available in Alpine Linux in the [[Repositories#Testing|testing repository]]. As it had no runtime dependencies, '''gummiboot''' was appreciated for its simplicity as a lightweight, minimal UEFI boot solution. Its UEFI stub, {{pkg|gummiboot-efistub}}, was used [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|to generate a Unified Kernel Images (UKIs)]] e.g. for [[DM-verity]] and Secure Boot, but [[Release_Notes_for_Alpine_3.22.0#Secure_Boot_and_Gummiboot|it has been deprecated since Alpine Linux 3.22]] and is no longer maintained; it has been replaced by '''systemd-efistub''' (note that the latter package [[UEFI_Secure_Boot#Generating_Unified_Kernel_Image|only supplies EFI stub binaries]] and doesn’t depend on any systemd components).

== Syslinux ==

If you want to switch from another bootloader back to ''Syslinux'', or if for some reason you want to install Syslinux manually, then the following steps are required.

Install the {{pkg|syslinux}} package:

{{cmd|# apk add syslinux}}

If you're using GPT partitions, then install the ''GPT MBR'' onto the drive that you want to install the bootloader on (in this case, {{path|/dev/sda}}):

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}

Or, if you're using DOS partitions, then install the ''DOS MBR'' instead:

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}


Next, install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS and UFS/FFS filesystems.

{{cmd|# extlinux --install /boot}}

The configuration file is located in {{path|/boot/extlinux.conf}}.

Alpine Linux ships with a script, <code>update-extlinux</code>, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.

You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory e.g. for dual booting.

=== Using EFI with syslinux ===

The Alpine Linux installer automatically uses [[#GRUB|GRUB]] if EFI mode is detected. The section below is specifically about using EFI with Syslinux.

Assuming that {{path|/mnt}} is a FAT32 partition of type EF00 and that {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:

{{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
# cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
# cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
# cp /boot/vmlinuz* /mnt/EFI/syslinux/
# cp /boot/initramfs* /mnt/EFI/syslinux/
</nowiki>}}

You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).

In the end, the {{path|/mnt/EFI/syslinux/syslinux.cfg}} file should look like this:

{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
DEFAULT menu.c32
PROMPT 0
MENU TITLE Alpine/Linux Boot Menu
MENU HIDDEN
MENU AUTOBOOT Alpine will be booted automatically in # seconds
TIMEOUT 10
LABEL lts
MENU DEFAULT
MENU LABEL Linux lts
LINUX /vmlinuz-lts
INITRD /initrd-lts
APPEND root=/dev/sda3 modules=sd-load,usb-storage,ext4 quiet
</nowiki>}}

Finally, add <code>syslinux</code> to the EFI boot menu. Assuming that {{path|/dev/sda}} is your hard drive —'''''be careful to check first what is its path on your device and to adjust accordingly''''':

{{cmd|<nowiki># apk add efibootmgr
# efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
</nowiki>}}

You can now verify that the boot entry has been added:

'''efibootmgr'''
<pre>
BootCurrent: 0001
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
</pre>

== rEFInd ==
{{Main|rEFInd}}

[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.

== GRUB ==

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}

For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI-compatible filesystem, such as FAT32.

{{cmd|# apk add grub-efi efibootmgr}}

Next, install the MBR and GRUB binaries to disk for BIOS mode:

{{cmd|# grub-install /dev/vda}}

For EFI mode:

{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}

Then, add this line to {{path|/etc/default/grub}}:

{{cat|/etc/default/grub|<nowiki># GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"</nowiki>}}

GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:

{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

This script can be configured via the {{path|/etc/default/grub}} file.

If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].

Consult [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html gnu.org's online manual] for a list of available <code>grub-mkconfig</code> configuration options.

== EFI Boot Stub ==

To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with ''efibootmgr''.

=== efibootmgr ===

Install {{Pkg|efibootmgr}}:
{{cmd|# apk add efibootmgr}}

Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.

{{cat|add-bootentry|<nowiki>#!/bin/sh

params="root=/dev/sdXZ rootfstype=ext4 rw \
initrd=\intel-ucode.img \
initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
--disk /dev/sdX --part Y \
--loader /vmlinuz-lts \
--unicode "${params}" \
--verbose
</nowiki>}}

Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-stable}}, then replace <code>lts</code> with <code>stable</code> in the script.

{{Tip|If you're modifying EFI records from a running system (e. g. migrating from GRUB), you can populate {{ic|$params}} from {{ic|/proc/cmdline}}. Make sure to append {{ic|initrd}} param if it's missing since GRUB does not add it to the command line.}}

{{Note| The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
}}

Optionally, set the newly-created entry as the default:

{{cmd|# efibootmgr -n XXXX}}

Where <code>XXXX</code> is the boot number of the new entry.

{{Note| The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update <code>fstab</code> to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}. }}

== Using a UKI ==

'''[https://github.com/uapi-group/specifications/blob/main/specs/unified_kernel_image.md#unified-kernel-image-uki Unified Kernel Image]''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.

The [[UEFI Secure Boot]] page contains the instructions for setting up an a UKI. While this is typically done in order to ''SecureBoot'', it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.

Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}} :

{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the stable kernel, install the UKI into the default UEFI path.
if [ "$1" == "stable" ]; then
output_dir="/efi/EFI/Boot/"
output_name="bootx64.efi"
fi
</nowiki>}}

{{Note| {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures, the exact name will vary.}}

== Troubleshooting ==

Since bootloaders are installed only during [[System Disk Mode]], the errors related to them are documented in [[System Disk Mode#Troubleshooting|that page]].

== See also ==
* [[Enable Serial Console on Boot]]
* [[Silent boot]]
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki - Bootloaders]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki - Boot loader]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki - Bootloaders]
* [https://docs.u-boot.org/en/latest/develop/release_cycle.html u-boot.org docs - U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

System Disk Mode

2026-02-10T14:34:42Z

Prabuanand: updated based on clarification from reddit user u/kenrmayfield

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

* If you are using [[Bootloaders#Syslinux|ExtLinux/SysLinux]], then ensure that {{Codeline|APPEND}} line in the file {{Path|/boot/extlinux.conf}} has <code>root=UUID=<UUID ID></code> or <code>root=/dev/sdXY</code> and the same matches the root path in the {{Path|/etc/fstab}} file. Also ensure that modules has the appropriate filesystem like <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
# root=UUID=<UUID ID> can be used also in the APPEND Line.
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to reboot the computer.

If the fsck command fixes the corruption but the Error:"Mounting Root Failed", still persists then the next step would be to rebuild the initram file system. After running fsck, mount the root partition and [[Chroot]] into the mounted root partition before running the mkinitfs command as shown in the [[Initramfs init|initramfs]] page.

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

System Disk Mode

2026-02-10T10:33:26Z

Prabuanand: added additional steps based on the detailed instructions provided by reddit user u/kenrmayfield here https://redd.it/1qyxwdo

System Disk mode is the traditional or classic harddisk installation of Alpine Linux. This installation mode is suitable for most use cases including generic [[Tutorials_and_Howtos#Desktop|desktop]], [[Setting up the build environment|development machine]] etc.

If an entire hard disk(s) is available for Alpine Linux, [[Installation#setup-alpine_based_System_Disk_Install|setup-alpine based install]] is the recommended way to install Alpine Linux. For all other use cases, follow the [[Alpine_setup_scripts#setup-disk|<code>setup-disk</code>]] based Installation given below.

== setup-disk based Installation ==

To perform a traditional hard-disk installation of Alpine Linux, after completing the base configuration, proceed to create, format and mount your partitions with MOUNTPOINT {{Path|'''/mnt'''}} as root and run the command {{Codeline|'''<Code>setup-disk -m sys /mnt</Code>'''}}.

# Follow the [[Installation#General_course_of_action|Installation guide]] to complete the [[Installation#Base_configuration|base configuration]], if not already done. A working [[Configure_Networking#Connectivity_testing|Internet access]] is mandatory to complete this installation.
# If necessary formatted partition(s) are unavailable, manually [[Setting up disks manually#Creating_partitions|create]] them first and [[Setting up disks manually#Formatting_partitions|format]] them including swap partition(if used). If you're using legacy BIOS mode, use DOS i.e MBR partition table and ensure that proper partition is bootable for [[Bootloaders#Syslinux|extlinux]].
# Mount the '''/ (root)''' partition on a mount point i.e say {{Path|/mnt}} as follows: {{Cmd|# mount /dev/sdXY /mnt}}
# If you're using [[UEFI|EFI]], create a mount point <code>/mnt/boot</code> and mount the EFI system partition(ESP) on it. {{Cmd|<nowiki># mkdir -p /mnt/boot
# mount /dev/sdXY /mnt/boot</nowiki>}}
# If [[Swap|swap]] partition is available, you can also enable it now: {{Cmd|# swapon /dev/sdXY }}
# Install Alpine Linux using the following command: {{Cmd|# setup-disk -m sys /mnt}}
# <code>setup-disk</code> will perform a traditional hard disk install of your running system, detects your file system layout and generates {{Path|/etc/fstab}} and installs a [[Bootloaders|bootloader]] based on the <Code>BOOTLOADER</Code> [[Alpine_setup_scripts#Environment_Variables|environment variable]].
# At the end of Installation, you can [[Installation#Reboot|reboot]] to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

== Troubleshooting ==

=== Mounting on /dev/sdXY sysroot failed ===

The error message appears as follows with variations in <code>/dev/sda8</code> depending on the partition number and SSD/HDD etc:

<Pre>
mounting /dev/sda8 on /sysroot failed: No such file or directory
mounting root: failed
initramfs emergency recovery shell launched. Type 'exit' to continue boot
sh: can't access tty: job control turned off
</Pre>

The above error message can be caused by various reasons. Follow the below steps in the emergency shell to identify one possible cause.

# Verify that the partition name in which Alpine Linux was installed matches the above [[#Mounting on /dev/sdXY sysroot failed|error]] by issuing the command and also note down the filesystem type of that partition (say TYPE="ext4") : {{Cmd| blkid}}
# If the expected disk (e.g., /dev/sda, /dev/nvme0n1) itself is missing in the output of {{ic| blkid}}, check [[#Disks not detected after setup-disk|Disks not detected after setup-disk]].
# Verify that sysroot exists by issuing the command. {{Cmd|ls -ld /sysroot}}
# Check if the above error message apears when issuing the command. {{Cmd|mount /dev/sda8 /sysroot}}
# If there is no error message, proceed to check if the issue is caused by a [[#Filesystem corruption|filesystem corruption]].
# If the manual mount command fails with "No such file or directory" even though you verified /sysroot exists in Step 3, this confirms the kernel doesn't recognize the filesystem type. Check whether filesystem modules(change ext4 if needed) are loaded by issuing the command. {{Cmd|<nowiki>lsmod | grep ext4 </nowiki>}}
# If there is no output, then it confirms that the above [[#Mounting on /dev/sdXY sysroot failed|issue]] is caused by [[#Missing filesystem modules in the kernel cmdline|missing filesystem module]].

==== Disks not detected after setup-disk====

After running the standard Alpine installation command: {{ic|setup-disk -m sys /mnt}} and rebooting, the system gives the error mentioned in [[#Mounting on /dev/sdXY sysroot failed|Mounting on /dev/sdXY sysroot failed]] with the expected disk (e.g., /dev/sda, /dev/nvme0n1) missing to show at the output of {{ic| blkid}}. This prevents booting into the installed system.

Issue: As per [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10615 bug report] this might be caused by BIOS storage controller being set to "RAID On (Intel Rapid Storage Technology)".

Resolution: Switch the storage mode in BIOS/UEFI: Go to BIOS → Storage or SATA/NVMe Operation. Change setting from:RAID On (Intel Rapid Storage Technology) to: AHCI or AHCI/NVMe.

==== Missing filesystem modules in the kernel cmdline ====

[[BusyBox]] mount command does not autoload modules, so need to add filesystem modules to the kernel cmdline. Even though alpine installer does this automatically, this has to be taken care of in case of manual disk install, particularly for [[Dualbooting|dualboot]] installations.

# To resolve, issue the command to load the appropriate filesystem module(say TYPE="ext4").{{Cmd|modprobe ext4}}
# To verify if the issue is resolved, reissue the command.{{Cmd|mount /dev/sda8 /sysroot}}
# If mount succeeded, issue the following command to boot into Alpine Linux. {{Cmd|exit}}

Choose the appropriate solution based on your use case for a permanent fix:

*If you are using [[Bootloaders#GRUB|grub]], then ensure that {{Codeline|GRUB_CMDLINE_LINUX}} line in the file {{Path|/etc/default/grub}} has the appropriate filesystem module <code>ext4</code> and <code>rootfstype=ext4</code> as follows: {{Cat|/etc/default/grub|<nowiki>...
GRUB_CMDLINE_LINUX="console=ttyS0,19200n8 net.ifnames=0 modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4"
...</nowiki>}}

*If you are using [[Bootloaders#Syslinux|Syslinux]], then ensure that {{Codeline|APPEND root}} line in the file {{Path|/boot/extlinux.conf}} has the appropriate filesystem module <code>ext4</code> as follows: {{Cat|/boot/extlinux.conf|<nowiki>...
APPEND root=/dev/sdXY modules=sd-mod,usb-storage,ext4 quiet
...</nowiki>}}

{{Note|For both above cases, you may need to issue {{Codeline|update-grub}} or {{Codeline|update-extlinux}} after making above changes.}}

*For a solution independent of [[Bootloaders|bootloaders]], ensure that the file {{Path|/etc/mkinitfs/mkinitfs.conf}} has the necessary filesystem module in it. Refer [[Initramfs init|Initramfs]] page for more information and recreate initramfs image.

==== Filesystem corruption ====

To fix filesystem corruption issues, the command fsck must be run on the root partition. The root partition should be umounted before running fsck. Boot from a [[Rescue disk]] to run the fsck command on the root partition:{{Cmd|<nowiki># fsck -y /dev/<DEVICE></nowiki>}}

After running fsck, proceed to reboot the computer.

If the fsck command fixes the corruption but the Error:"Mounting Root Failed", still persists then the next step would be to rebuild the initram file system. After running fsck, mount the root partition and [[Chroot]] into the mounted root partition before running the mkinitfs command as shown in the [[Initramfs init|initramfs]] page.

=== Blinking underscore ===

On a UEFI system, at the end of Installation after rebooting, the computer screen may appear with a '''blinking underscore'''. This may be due to the firmware not finding a valid boot entry.

The [[UEFI#EFI bootloaders|EFI bootloader]] entries are added without writing to NVRAM, thus preventing GRUB from calling {{ic|efibootmgr}}. In some cases the UEFI firmware may not boot from a bootloader without a valid NVRAM entry. In such cases, at the end of installation, instead of rebooting, manually add an entry for Alpine Linux in the NVRAM as follows:
* Install the {{pkg|efibootmgr}} package:{{Cmd|# apk add efibootmgr}}
* Adjust the device name {{ic|/dev/sdX}} and partition number {{ic|1}}, before issuing the command: {{Cmd|# efibootmgr --create --disk /dev/sdX --part 1 --label "Alpine" --loader '\EFI\alpine\grubx64.efi'}}

== See also ==

* [[Bootloaders]] - For information on GRUB, Syslinux and rEFInd
* [[Installing Alpine on HDD dualbooting|Install to HDD with dual-boot]]
* [[Installing Alpine Linux in a chroot|Installing Alpine Linux in a chroot]]
* [https://github.com/itoffshore/alpine-linux-scripts setup-partitions]

[[Category:Installation]]

PipeWire

2026-02-09T05:58:25Z

Prabuanand: updated wiki based on message by invoked on 2026-02-08 16:49:14 in https://irclogs.alpinelinux.org/%23alpine-linux-2026-02.log

{{TOC right}}
[https://pipewire.org/ PipeWire] is a multimedia processing engine that aims to improve audio and video handling on Linux. PipeWire can act as a replacement for both [[PulseAudio]] and [[ALSA]] servers.

== Prerequisites ==

* PipeWire requires [[D-Bus#D-Bus_session_bus|D-Bus session bus]] for most of its functionality.
* Ensure that your [[Setting_up_a_new_user#Creating_a_new_user|non-root user account]] has appropriate [[Setting_up_a_new_user#Groups_for_desktop_usage|groups for desktop usage]].
* WirePlumber requires [[eudev]] for ALSA device discovery.

== Installation ==

Install {{Pkg|pipewire}} and {{Pkg|wireplumber}} (session manager).

{{Cmd|# apk add pipewire wireplumber}}

=== Pulseaudio interface ===

The package {{Pkg|pipewire-pulse}} allows pulseaudio applications and [[#GUI_tools|GUI tools]] to use PipeWire as audio server in the backend.

{{Cmd|# apk add pipewire-pulse}}

=== JACK compatibility ===

Since PipeWire replaces JACK, Install {{Pkg|pipewire-jack}} package, so it provides ABI-compatible libraries for JACK applications.

{{Cmd|# apk add pipewire-jack}}

=== ALSA support ===

Install {{Pkg|pipewire-alsa}} package to provide support for ALSA applications.

{{Cmd|# apk add pipewire-alsa}}

=== GUI tools ===

* {{Pkg|pavucontrol}}: simple GUI app for controlling sound, outputs, etc. Consider using {{Pkg|pavucontrol-qt}} when using [[KDE|Plasma]].

: [[#Pulseaudio_interface|Pulseaudio interface]] is mandatory for {{Ic|pavucontrol}} to work with PipeWire.

* {{Pkg|xfce4-mixer}}: XFCE Audio mixer.

: Currently available in the [[Repositories#Testing|testing]] repository.

* {{Pkg|qpwgraph}}: graph manager dedicated to PipeWire with Qt GUI Interface.

== Launch PipeWire ==

Most [[Desktop_environments_and_Window_managers#Desktop_environments|desktop environments]] launch PipeWire automatically in Alpine Linux upon relogging (i.e. logging out and logging in) after [[#Installation|installing the above packages]]. Proceed with the section below only if PipeWire is [[#Testing|not launched]] after a relogin/reboot.

{{Note|[[#PipeWire_user_service|PipeWire user service]] is the recommended method to launch PipeWire and will replace [[#pipewire-launcher|pipewire-launcher]]. Do '''NOT''' use both methods to avoid running multiple instances of PipeWire.}}

=== PipeWire user service ===

Since [[Release_Notes_for_Alpine_3.22.0#OpenRC_User_services|Alpine 3.22]], PipeWire can be launched as a user service.

==== User service prerequisites ====

* Ensure the [[OpenRC#Prerequisites|OpenRC User service Prerequisites]] are met and [[OpenRC#Configure environment variables|environment variables are configured]].
* PipeWire will fail to start, if [[#Realtime scheduling|realtime scheduling]] is not configured.
* Issue the command {{ic|$ rc-status -Ur}} to view and verify the current user runlevel as '''gui''' and '''default''' for Wayland and Xorg respectively.

==== User service management ====

To start the {{Ic|pipewire}} user service and its {{Ic|wireplumber}} session manager:

{{Cmd|$ rc-service -U pipewire start
$ rc-service -U wireplumber start}}

To enable the {{Ic|pipewire}} and {{Ic|wireplumber}} user services in [[Wayland]], in [[Xorg]] change {{Ic|gui}} to {{Ic|default}}:

{{Cmd|$ rc-update -U add pipewire gui
$ rc-update -U add wireplumber gui}}

The above steps may be repeated for {{Ic|pipewire-pulse}} user service.

{{Note|The {{ic|pipewire-pulse}} user service would be required to enable various functions, including setting audio levels with {{ic|pactl}}, when [[PulseAudio#PulseAudio_Utils|running pulseaudio with pulseaudio-utils]] and to enable associated volume user keys.}}

=== pipewire-launcher ===

{{Note|The {{Ic|pipewire-launcher}} script will be removed in the future to be replaced with the [[#PipeWire_user_service|PipeWire user service]].}}

Launch PipeWire by using the <code>pipewire-launcher</code> script. You'll probably get quite a few errors but just ignore them for now.

{{Cmd|$ /usr/libexec/pipewire-launcher}}

If xinitrc is used, add {{Path|/usr/libexec/pipewire-launcher}} to your {{Path|~/.xinitrc}}.

If you do not use GUI by default, add the following stanza to your shell configuration file:

{{Cmd|export $(dbus-launch)
/usr/libexec/pipewire-launcher}}

== Configuration ==

PipeWire and WirePlumber store their default configuration in {{Path|/usr/share/pipewire}} and {{Path|/usr/share/wireplumber}} respectively. If you want to edit the configuration, you need to move it to {{Path|/etc}}:

{{Cmd|<nowiki># cp -a /usr/share/pipewire /etc
# cp -a /usr/share/wireplumber /etc</nowiki>}}

=== Screen sharing on Wayland ===

Applications which don't implement native Wayland screensharing rely on [https://github.com/flatpak/xdg-desktop-portal xdg-desktop-portal] plus the correct backend for your compositor. Screen sharing is known to work on:
* GNOME with <code>xdg-desktop-portal-gtk</code>
* KDE Plasma with <code>xdg-desktop-portal-kde</code> and Firefox
* Sway with <code>xdg-desktop-portal-wlr</code> and Firefox, see [[Sway]] for details

=== Bluetooth audio ===
{{Main|Bluetooth}}
* Enable PulseAudio support as described above
* Install bluetooth service packages: <code>bluez bluez-openrc pipewire-spa-bluez</code>
* Optional: install GUI manager for bluetooth <code>blueman</code>
* Enable and start bluetooth service: <code>rc-update add bluetooth; rc-service bluetooth start</code>
* Restart PipeWire
* Use commandline program <code>bluetoothctl</code> or GUI program <code>blueman-manager</code> to scan and pair bluetooth audio devices.
* Use pavucontrol to adjust volume and manually select high definition bluetooth codecs.

=== Video ===

Video should work out-of-the-box with v4l2 devices (e.g. a lot of webcams) and [https://gstreamer.freedesktop.org/ GStreamer] applications.

=== Realtime scheduling ===

Realtime scheduling will increase certain threads priorities to assist with low latency audio processing. By default, PipeWire tries to enable realtime scheduling with the [https://docs.pipewire.org/page_module_rt.html rt module].

==== Option1 ====

Since [https://gitlab.freedesktop.org/pipewire/pipewire/-/releases/0.3.66 PipeWire 0.3.66], when you have a [[PAM]] login session, you should add your user to the {{Ic|pipewire}} group.

==== option2 ====

If you don't have [[PAM]] but [[D-Bus]] is available, the rt module will try to use {{Pkg|rtkit}}; if this is the case, add your user to the {{Ic|rtkit}} group.

The default system wide settings are defined in {{Path|/etc/security/limits.d/25-pw-rlimits.conf}}. You may want to adjust settings for parameters like <var>rt.prio</var>, if required. Alternatively, it can be set at [https://docs.pipewire.org/page_module_rt.html user level] within the ceiling set by the system's rlimits.

{{Cat|~/.config/pipewire/pipewire.conf.d/my-rt-args.conf|<nowiki>context.modules = [
{ name = libpipewire-module-rt
args = {
#nice.level = 20
#rt.prio = 88
}
flags = [ ifexists nofail ]
}
]</nowiki>}}

== Testing ==

Use the <code>wpctl</code> utility from {{Pkg|wireplumber}} to test the working of PipeWire:

{{Cmd|$ wpctl status}}

=== pw-cat playback ===

Test sound is working using an audio file in a format supported by [http://www.mega-nerd.com/libsndfile/ libsndfile]{{insecure url|Server refuses HTTPS connections}} (e.g. flac, opus, ogg, wav). Use <code>pw-cat</code> utility from {{Pkg|pipewire-tools}}:

{{Cmd|$ pw-cat -p test.flac
$ pw-play /usr/share/sounds/alsa/Front_Center.wav
}}

=== pw-cat recording ===

If you have a microphone test audio recording is working.

{{Cmd|$ pw-cat -r --list-targets
$ pw-cat -r recording.flac
(Speak for a while then stop it with Ctrl+c)
$ pw-cat -p recording.flac
}}

=== PulseAudio ===

Test PulseAudio clients using a media player, as most use PulseAudio.

=== JACK ===

Use <code>jack_simple_client</code> from {{Pkg|jack-simple-clients}}:

{{Cmd|$ jack_simple_client}}

You should hear a sustained beep.

== Troubleshooting ==

=== `wpctl status` shows no targets ===

First, check whether ALSA knows about your sound card using the <code>aplay</code> utility from {{pkg|alsa-utils}} package:

{{Cmd|$ aplay -l}}

If sound devices are found, the issue is likely with your PipeWire configuration. Ensure that [[eudev]] is installed, and consider double-checking the instructions above.

If no sound devices are found, your sound card may not be supported in the version of the Linux Kernel you're running. You should search online for fixes relating to your current kernel version and the codec of your sound card. You can find each of these with:

{{Cmd|$ uname -r
$ cat /proc/asound/card0/codec* {{!}} grep Codec}}

Modern devices might require {{Pkg|sof-firmware}}, which is the case if you get <code>sof firmware file is missing</code> errors in dmesg.

=== Error acquiring bus address: Cannot autolaunch D-Bus without X11 $DISPLAY ===

Check and ensure that [[D-Bus#D-Bus session bus|D-Bus session bus]] is started along with your GUI session i.e. you are in a tty.

=== Connection failure: Connection refused ===

When using [[Wayland]], ensure that [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] is configured correctly. If this is not set, PipeWire will create a directory in your home folder instead, called {{Path|~/pulse}}, and on attempting to run {{Ic|pavucontrol}} or {{Ic|pactl}}, you will get the following error:

{{Cmd|$ pactl list
Connection failure: Connection refused
pa_context_connect() failed: Connection refused}}

If you are running Alpine 3.22+ and continue to experience this error after verifying that [[Wayland#XDG_RUNTIME_DIR|XDG_RUNTIME_DIR]] is correctly set, ensure that the <code>pipewire-pulse</code> [[#PipeWire_user_service|user service is running]].

=== Bluetooth connect failed: br-connection-profile-unavailable ===

Ensure {{Ic|wireplumber}}, the session manager, is running.

=== Play/Pause buttons not working on bluetooth headphones ===

Check {{Path|/var/log/messages}} for lines similar to:

{{Cat|/var/log/messages|bluetoothd[3463]: profiles/audio/avctp.c:uinput_create() Can't open input device: No such file or directory (2)
bluetoothd[3463]: profiles/audio/avctp.c:init_uinput() AVRCP: failed to init uinput for WH-1000XM5}}

Then {{Ic|bluez}} is trying to register the headphones buttons as an input devices, but <code>uinput</code> is not loaded. Try <code>modprobe uinput</code>. If this works, see [[Architecture#Loading_of_Kernel_Modules|Loading of Kernel Modules]] for instructions on how to make sure this module is loaded automatically on each startup.

=== RTKit error: org.freedesktop.DBus.Error.ServiceUnknown ===

mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:995:do_rtkit_setup: RTKit does not give us MaxRealtimePriority, using 1
mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:1000:do_rtkit_setup: RTKit does not give us MinNiceLevel, using 0
mod.rt ../src/modules/module-rt.c:330:translate_error: RTKit error: org.freedesktop.DBus.Error.ServiceUnknown
mod.rt ../src/modules/module-rt.c:1005:do_rtkit_setup: RTKit does not give us RTTimeUSecMax, using -1

Follow [[#Realtime scheduling|Realtime scheduling]] section to resolve the above error message.

== See also ==

* [[Bluetooth]]
* Official PipeWire links
** [https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home Wiki]
** [https://docs.pipewire.org Documentation site]
** [https://gitlab.freedesktop.org/pipewire/pipewire Source repository]
* [https://wiki.archlinux.org/index.php/PipeWire PipeWire on the ArchWiki]
* [https://wiki.gentoo.org/wiki/PipeWire PipeWire on the Gentoo Wiki]

[[Category:Sound]]

Installation

2026-02-05T05:24:50Z

Prabuanand: added comment to future editors

[[Image:hdd_mount.png|left|link=]]
 

This page exists to provide a basic overview to get started. Before actually installing, it can help to skim through the [[Alpine_Linux:FAQ| Frequently Asked Questions (FAQ)]], as well as to refer to the official installation guide at [https://docs.alpinelinux.org/ docs.alpinelinux.org].

{{Tip|This is a wiki!
If something isn't correct, or is incomplete, you will have to figure it out, or ask for the correct solution in the [https://alpinelinux.org/community/ community].

And then carefully [[Help:Editing|edit]] the wiki page.

Just as those before who did it for you.}}

== Minimal Hardware Requirements ==
{{Main|Requirements}}
* At least 128 MB of RAM. [A graphical desktop system may require up to 512 minimum.]. Note that an installation itself (from ISO) generally requires at least 320 MB during installation.
* At least 0-700 MB space on a writable storage device. [Only required in [[#System Disk Mode|"sys"]] or [[#Data Disk Mode|"data"]] mode installations. It is optional in [[#Diskless Mode|"diskless"]] mode, where it may be used to save newer data and configurations states of a running system.]
* A working internet connection is required to complete [[#System Disk Mode|"sys"]] mode installation or use '''Extended image''' if available for your architecture.

{{Note|Refer [[#Custom Installation Instructions|custom installation instructions]] for headless system, virtualization etc. Most of the steps outlined on this page applies to all [[Architecture#Architectures_supported|Architectures]] supported by Alpine Linux. For more specific installation instructions, refer to their respective pages.}}

== Installation Overview ==

Alpine Linux can be installed and run in three modes i.e [[#Diskless_Mode|Diskless Mode]], [[#Data_Disk_Mode|Data Disk Mode]] and [[#System_Disk_Mode|System Disk Mode]]. The first two installation modes are sometimes referred to, collectively, as "run-from-RAM" installations. The installation procedure for Alpine Linux '''requires basic understanding of the three modes''' explained in brief below:

==== Diskless Mode ====
{{Main|Diskless Mode}}
In Diskless mode the entire operating system with all applications are first loaded into RAM and then only run from there. This mode is extremely fast and can save on unnecessary disk spin-ups, power, and wear. Alpine Linux uses this method to boot the .iso installation images. The [[Alpine_setup_scripts#setup-alpine|<code>setup-alpine</code>]] script configures the installed system to continue to boot like this if "disk=none" is specified.

==== Data Disk Mode ====
{{Main|Data Disk Mode}}
In Data Disk mode also the operating system runs from system RAM, thus it enjoys the same accelerated operation speed as "diskless" mode. However, swap storage and the entire {{Path|/var}} directory tree get mounted from a persistent storage device. This mode is useful for having RAM accelerated servers with variable amounts of user-data that exceed the available RAM size.

==== System Disk Mode ====
{{Main|System Disk Mode}}
System or '''sys''' Disk Mode is the traditional hard-disk install. Alpine Linux can be installed to an [[#setup-alpine based System Disk Install|'''entire hard disk''' using ''setup-alpine'']] script or to a [[System Disk Mode|'''partition''' using ''setup-disk'']] script.

=== General course of action ===

It is really helpful for many use cases to [[#Preparing for the installation|prepare]] and complete the [[#Installation Step Details|installation]] until the [[#Base configuration|base configuration]] step, then proceed with installation of the target system with any one of the various [[#Alternative courses of action|alternative]] courses of action.

=== Alternative courses of action ===

Examples of preparation options:

* Download specific driver to configure [[Alpine_kernel_module_support#List_of_out-of-tree_kernel_module_packages|hardware]], if the [[Kernels#Firmware|firmware]] does not have it and/or install some software tool that may be missing in the live system by using the Alpine package manager <code>[[Alpine Package Keeper|apk]]</code>.
* Do a [[Setting up disks manually#Manual partitioning|manual partitioning]] of the hard disk that avoids overwrite of an entire disk.

Examples of such options:

* To install Alpine Linux on an '''entire hard disk''' with optional [[Alpine setup scripts#Environment Variables|environment variables]], proceed to [[#setup-alpine based System Disk Install|setup-alpine based System Disk Install]].
* Use {{ic|setup-disk}} script to complete a [[System Disk Mode|traditional hard disk installation]] on a partition or to [[Dualbooting|dualboot]] or to configure [[Setting up disks manually#RAID|RAID]], [[Setting up disks manually#Encryption|encryption]] or [[Setting up disks manually#LVM|LVM]] for [[#System Disk Mode|"system"]] disk mode or to add a [[#Data Disk Mode|"data"]] mode partition.
* Create a [[Create a Bootable Device#Using setup-bootable|customizable boot media]] i.e a boot device with a writable filesystem for '''[[#Diskless Mode|diskless]]''' or '''[[#Data Disk Mode|data]]''' disk-mode.
* Configure a [[Diskless Mode#Using an internal disk for persistent storage|internal disk for persistent storage]] to save the local configuration state and local package cache for the [[#Diskless Mode|diskless]] system or '''[[#Data Disk Mode|data]]''' disk-mode.

There are many more [[Alpine setup scripts|setup-scripts]] available. All these tools may also be run later to adjust specific configurations. For example, to set up a graphical environment as covered under [[#Post-Installation|Post-Installation]] below.

== Preparing for the installation ==

=== Downloading installation image ===

Installation image files are available in the '''iso''', '''tar.gz''', and '''img.gz''' formats. Download the [https://alpinelinux.org/downloads/ stable release installation image file] for the target computer's architecture with the corresponding <code>sha256</code> checksum and <code>GPG</code> signature files.
{{Tip|Only download the <code>sha256</code> checksum and <code>GPG</code> signature files from the [https://alpinelinux.org/downloads/ official site] and not from mirrors.}}

Now you have three files in the following format:
<pre>
alpine-standard-*.iso
alpine-standard-*.iso.sha256
alpine-standard-*.iso.asc
</pre>

<code>alpine-standard-{{AlpineLatest}}-x86_64.iso</code> is the '''standard''' image file for version '''{{AlpineLatest}}''' and the '''x86_64''' architecture in the '''iso''' format.

=== Verifying downloaded image ===

From Security point of view, verify the downloaded image file for both checksum and GPG signature before proceeding further. The three required utilities i.e <code>sha256</code>, <code>curl</code> and <code>gpg</code> or their equivalents are available in every operating system including Linux, windows, Mac and BSD derivaties.

{{Tip|Ensure that all the three downloaded files remain in the same folder. If not, adjust the commands accordingly.}}

The <code>sha256</code> checksum verifies the integrity of the downloaded image i.e no modifications occurred during download.
{{Cmd|sha256sum -c alpine-*.iso.'''sha256'''}}

The <code>GPG</code> signature verifies the link between the downloaded image to the individual who signed it. Signature verification involves two steps:

Step 1. Download and import the gpg signature from official website
{{Cmd|curl https://alpinelinux.org/keys/ncopa.asc | gpg --import ;}}

Step 2. Verify that the image signature matches with the one downloaded in Step 1.
{{Cmd|gpg --verify alpine-*.iso.'''asc''' alpine-*.'''iso'''}}

=== Preparing installation media ===
{{Seealso|Burning ISOs}}

{{Warning|All data currently on the installation media will be '''erased''', when Alpine Linux installation image is written on it. Correctly identify the device name for the installation media using commands <code>lsblk</code> and <code>blkid</code>.}}
If downloaded image file is in '''img.gz''' format, unzip it using the command {{ic|gunzip alpine-rpi-{{AlpineLatest}}-aarch64.img.gz}} to {{ic|alpine-rpi-{{AlpineLatest}}-aarch64.img}} first before using with {{ic|dd}} command. In Linux {{ic|dd}} command can be used to write image files in both '''iso''' and '''img''' format to the installation media.

If '''tar.gz''' format image file is downloaded, follow the [[Create a Bootable Device#Manually copying Alpine files|instructions]] to create the installation media.

Modify the input file('''if''') of the {{ic|dd}} command according to the name and path to your image file and and the target device i.e output file('''of''') should be a device name '''/dev/sdX''' instead of partition like '''/dev/sdbXY''':{{Cmd|# dd if{{=}}alpine-standard-{{AlpineLatest}}-x86_64.iso of{{=}}/dev/sdX bs{{=}}4M status{{=}}progress; eject /dev/sdX}}

If your version of <code>dd</code> does not support the option "status=progress", remove it. The <code>eject</code> command removes the target device from the system and ensures the write cache is completely flushed.

In Windows and Mac OS, [https://www.balena.io/etcher/ Etcher] can be used to create an installation media.

=== Verifying Installation media ===

After detaching and re-attaching the device, a bit-wise comparison can verify the data written to the device (instead of just data buffered in RAM). If the comparison terminates with an end-of-file error on the .iso file side, all the contents from the image have been written (and re-read) successfully:

{{Cmd|# cmp ~/Downloads/alpine-standard-{{AlpineLatest}}-x86_64.iso /dev/sdX
cmp: EOF on alpine-standard-{{AlpineLatest}}-x86_64.iso</Code>}}

=== Booting Installation Media ===

Insert the [[#Preparing_installation_media|Installation media]] to a proper drive or port of the computer and turn the machine on, or restart it, if already running.
{{Note| To successfully boot and install Alpine Linux, disable [[UEFI#Secure boot|secure boot]] in the BIOS. Once Alpine Linux is installed, this can be [[UEFI_Secure_Boot|enabled]].}}
If the computer does not automatically boot from the desired device, one needs to bring up the boot menu and choose the media to boot from. Depending on the computer, the menu may be accessed by repeatedly pressing a key quickly when booting starts. Some computers require that you press the button ''before'' starting the computer and hold it down while the computer boots. Typical keys are: {{key|F9}}-{{key|F12}}, sometimes {{key|F7}} or {{key|F8}}. If these don't bring up the boot menu, it may be necessary to enter the BIOS configuration and adjust the boot settings, for which typical keys are: {{key|Del}} {{key|F1}} {{key|F2}} {{key|F6}} or {{key|Esc}}.

== Installation Step Details ==

=== Boot Process ===

The boot process of the alpine installation image first copies the entire operating system into the RAM memory, and then starts a complete Alpine Linux system from there. It will initially only provide a basic command line environment that does not depend on reading from any (possibly slow) initial boot media, anymore.

Local log-in is possible as the user <code>root</code>. Initially, the '''root''' user has no password.

At the command prompt, an interactive script named [[Alpine_setup_scripts#setup-alpine|<code>setup-alpine</code>]] is available to configure and install Alpine Linux. The script can be customized by the optional [[Alpine_setup_scripts#Environment_Variables|environment variables]], in case of [[Installation#Data_Disk_Mode|'''"data"''']] or [[Installation#System_Disk_Mode|'''"sys"''']] mode. For e.g {{Codeline|<code>USE_EFI{{=}}1 BOOT_SIZE{{=}}512 setup-alpine</code>}}, sets the disklabel type to gpt, creates 512MB '''/boot''' partition with '''vfat''' filesystem and uses <code>grub</code> as bootloader.

=== Base configuration ===

Launch the Alpine Linux Installation by running the [[Alpine_setup_scripts#setup-alpine|<code>setup-alpine</code>]] script :

{{Cmd|# setup-alpine}}

The question-and-answer dialog of <code>setup-alpine</code> takes care of the base configuration. It sets up a network connection to access Internet to configure the system to boot into one of three different Alpine Linux "disk" modes: [[Installation#Diskless_Mode|'''"diskless"'''(none)]], [[Installation#Data_Disk_Mode|'''"data"''']] or [[Installation#System_Disk_Mode|'''"sys"''']]. If you choose to edit any option, the relevant file is opened in [[BusyBox#vi| '''vi''' editor]] for editing.

{{Tip| If you have access to a wired network, consider using [https://docs.alpinelinux.org/user-handbook/0.1a/Installing/setup_alpine.html#_setup_alpine_q Quick Mode], to complete the base configuration quickly.}}

[[File:Installation-alpine-alpine-setup-3-setup-scripts.png|350px|thumb|right|Example <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> session]]

The <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> script offers the following configuration options:

# '''Keyboard Layout''' (Local keyboard language and usage mode, e.g. ''us'' and variant of ''us-nodeadkeys''.)
# '''Hostname''' (The name for the computer.)
# '''Network ''' (Set up network connection to access Internet.)
#* Available interfaces are: '''eth0''' '''wlan0'''.(List depends on your hardware.)
#* Which one do you want to initialize? (or '?' or 'done') [eth0] (Enter 'done' after configuring '''atleast''' one interface for Internet access.)
#* Do you want to do any manual network configuration? (y/n) [n] (Default uses "DHCP".)
# '''DNS Servers''' (If none of the interfaces configured in previous step uses dhcp, set DNS server. If unsure, leave DNS domain name blank and using <code>[https://quad9.net/ 9.9.9.9 2620:fe::fe]</code> for DNS is typically adequate.)
# '''Root password''' (the password used to login to the root account)
# '''Timezone''' (Optionally display times/dates in your local time zone)
# '''HTTP/FTP Proxy''' (Proxy server to use for accessing the web/ftp. Use "none" for direct connections to websites and FTP servers.)
# '''Mirror''' (From where to download packages. Choose the organization you trust giving your usage patterns to.)
# '''Set up a user''' (Setting up a regular user account)
# '''NTP''' (Network Time Protocol client used for keeping the system clock in sync with a time server. Default is "busybox".)
# '''SSH''' (Secure SHell remote access server. "OpenSSH" is part of the default install image. Use "none" to disable remote login, e.g. on laptops.)
# In most cases, either one of following line(s) is displayed as follows:
#: '''No disks found.''' or ''' Available disks are: sda (128.0 GB JMicron Tech )'''
# '''Disk Mode''' ( A pre-setup of the "diskless" system or base configuration is completed by answering "none" when asked for the following questions.)
#* Which disk(s) would you like to use? (or '?' for help or 'none') '''none'''
#* Enter where to store configs (/media/ or 'none') '''none'''
#* The location of the package cache '''none'''

Base configuration is complete with the above step. Refer to the [[#Alternative courses of action|alternative courses of action]] to proceed further.

=== setup-alpine based System Disk Install ===

<code>setup-alpine</code> script based system disk installation, needs an ''' entire hard disk(s)''' for Alpine Linux and uses a partitioning layout with (/)root partition, /boot partition and a swap partition, where [[Alpine_setup_scripts#Environment_Variables|environment variables]] determine filesystem, size of the boot partition and the bootloader used. If your use case matches the above, at the final step of [[#Base configuration|base configuration]], type the appropriate hard disk '''device name''' instead of '''none'''. If multiple disks are chosen, [[Alpine_setup_scripts#RAID|RAID]] is used.

* At the '''Disk Mode''' stage, '''sda''' or relevant disk(s) must be chosen in the below screen:
** Which disk(s) would you like to use? (or '?' for help or 'none') '''sda'''
** Confirmation for the chosen disk(s) appears. ''The following disk is selected:'' '''sda (128.0 GB JMicron Tech ).'''
{{Warning|Pay close attention to the disk name and size. If you enter '''sys''' in the next step, no further questions will be asked and data on the chosen disk(s) will be overwritten!. Enter {{key|Ctrl}}+{{key|c}} to abort the installation process. Proceed only if you are 100% sure.}}
* How would you like to use it? ('sys', 'data', 'lvm' or '?' for help) '''sys'''

If '''sys''' is chosen, the <code>setup-alpine</code> script will complete the traditional hard-disk installation of Alpine Linux on the chosen disk(s) without further questions. Once the installation is complete, you can skip the next steps and proceed to [[#Reboot|reboot]] the system to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

=== Custom partitioning ===

[[Setting_up_disks_manually#Manual_partitioning|Manual partitioning]] of the harddisk may be needed to prepare the harddisk for "sys" mode install using [[System Disk Mode|<code>setup-disk</code>]] script and for storing the config file using [[Alpine_local_backup|<code>lbu commit</code>]] and package cache for [[Diskless Mode|Diskless]] and for '''/var''' mount for [[Data Disk Mode|Data disk]] mode installs. Refer [[Setting up disks manually|Setting up disks manually]] page for specific configurations related to [[Setting_up_disks_manually#RAID|RAID]], [[Setting_up_disks_manually#Encryption|encryption]], [[Setting_up_disks_manually#LVM|LVM]], etc...

=== Preparing for the first boot ===

If [[#System_Disk_Mode|System Disk Mode]] of installation was performed, ignore this section and proceed to [[#Reboot|reboot]].

If the new local system was configured to run in "diskless" or "data" mode, and you do not want keep booting from the initial (and possibly read-only) [[Installation#Preparing_installation_media|installation media]], create a [[Create_a_Bootable_Device|customizable boot device]]. Once everything is in place, save your customized configuration with {{ic|lbu commit}} before rebooting.

=== Reboot ===

First, remove the initial installation media from the boot drive, or detach it from the port it's connected to. The system may now be power-cycled or rebooted to confirm everything is working correctly. The relevant commands for this are {{ic|poweroff}} or {{ic|reboot}}. Login into the new system with the root account.

=== Completing the installation ===

The installation script installs only the base operating system. '''No''' applications e.g. web server, mail server, desktop environment, or web browsers are installed.

Please look at [[Installation#Post-Installation|Post-Installation]], for some common things to do after installation.

== Custom Installation Instructions ==


* [[Installation on a headless host]]
* [[Kernels]] ''(kernel selection, e.g. for VMs or RPi)''
* [[How to make a custom ISO image with mkimage]] ''(installation media with its own configuration)''
* [[Directly booting an ISO file]] ''(without flashing it to a disk or device)''
* [[Alpine Linux in a chroot]]
* [[Netboot Alpine Linux using iPXE]]
* [[:Category:Virtualization|Virtualization]]
* [[Using an answerfile with setup-alpine]]

Also see other [[:Category:Installation|Installation category]] pages.

== Post-Installation ==

{{Tip|Alpine Linux packages stay close to the upstream design. Therefore, all upstream documentation about configuring a software package, as well as good configuration guides from other distributions that stay close to upstream, e.g. those in the [https://wiki.archlinux.org/ ArchWiki], or [https://wiki.gentoo.org/wiki/ Gentoo wiki] are to a large degree, also applicable to configuring the software on Alpine Linux, thus can be very useful.}}


* [[Tutorials_and_Howtos#Desktop|Desktop 'How To']] - Alpine Linux as a desktop OS
* [[Tutorials_and_Howtos#Services|Hosting services]] - Such as mail/web/ssh/Firewall/VPN servers
* [[Tutorials_and_Howtos#Virtualization|Virtualization]] guide - For using Alpine Linux as both guest and host
* Guide to [[OpenRC|OpenRC]] - Init system used to configure services
* Create and maintain a [[Rescue disk]]

== See also ==

* [[Tutorials and Howtos]]
* [[Comparison with other distros]] ''(how common things are done on Alpine)''

[[Category:Installation]]

Installation

2026-02-05T05:16:46Z

Prabuanand: moved content to Rescue disk

[[Image:hdd_mount.png|left|link=]]
 

This page exists to provide a basic overview to get started. Before actually installing, it can help to skim through the [[Alpine_Linux:FAQ| Frequently Asked Questions (FAQ)]], as well as to refer to the official installation guide at [https://docs.alpinelinux.org/ docs.alpinelinux.org].

{{Tip|This is a wiki!
If something isn't correct, or is incomplete, you will have to figure it out, or ask for the correct solution in the [https://alpinelinux.org/community/ community].

And then carefully [[Help:Editing|edit]] the wiki page.

Just as those before who did it for you.}}

== Minimal Hardware Requirements ==
{{Main|Requirements}}
* At least 128 MB of RAM. [A graphical desktop system may require up to 512 minimum.]. Note that an installation itself (from ISO) generally requires at least 320 MB during installation.
* At least 0-700 MB space on a writable storage device. [Only required in [[#System Disk Mode|"sys"]] or [[#Data Disk Mode|"data"]] mode installations. It is optional in [[#Diskless Mode|"diskless"]] mode, where it may be used to save newer data and configurations states of a running system.]
* A working internet connection is required to complete [[#System Disk Mode|"sys"]] mode installation or use '''Extended image''' if available for your architecture.

{{Note|Refer [[#Custom Installation Instructions|custom installation instructions]] for headless system, virtualization etc. Most of the steps outlined on this page applies to all [[Architecture#Architectures_supported|Architectures]] supported by Alpine Linux. For more specific installation instructions, refer to their respective pages.}}

== Installation Overview ==

Alpine Linux can be installed and run in three modes i.e [[#Diskless_Mode|Diskless Mode]], [[#Data_Disk_Mode|Data Disk Mode]] and [[#System_Disk_Mode|System Disk Mode]]. The first two installation modes are sometimes referred to, collectively, as "run-from-RAM" installations. The installation procedure for Alpine Linux '''requires basic understanding of the three modes''' explained in brief below:

==== Diskless Mode ====
{{Main|Diskless Mode}}
In Diskless mode the entire operating system with all applications are first loaded into RAM and then only run from there. This mode is extremely fast and can save on unnecessary disk spin-ups, power, and wear. Alpine Linux uses this method to boot the .iso installation images. The [[Alpine_setup_scripts#setup-alpine|<code>setup-alpine</code>]] script configures the installed system to continue to boot like this if "disk=none" is specified.

==== Data Disk Mode ====
{{Main|Data Disk Mode}}
In Data Disk mode also the operating system runs from system RAM, thus it enjoys the same accelerated operation speed as "diskless" mode. However, swap storage and the entire {{Path|/var}} directory tree get mounted from a persistent storage device. This mode is useful for having RAM accelerated servers with variable amounts of user-data that exceed the available RAM size.

==== System Disk Mode ====
{{Main|System Disk Mode}}
System or '''sys''' Disk Mode is the traditional hard-disk install. Alpine Linux can be installed to an [[#setup-alpine based System Disk Install|'''entire hard disk''' using ''setup-alpine'']] script or to a [[System Disk Mode|'''partition''' using ''setup-disk'']] script.

=== General course of action ===

It is really helpful for many use cases to [[#Preparing for the installation|prepare]] and complete the [[#Installation Step Details|installation]] until the [[#Base configuration|base configuration]] step, then proceed with installation of the target system with any one of the various [[#Alternative courses of action|alternative]] courses of action.

=== Alternative courses of action ===

Examples of preparation options:

* Download specific driver to configure [[Alpine_kernel_module_support#List_of_out-of-tree_kernel_module_packages|hardware]], if the [[Kernels#Firmware|firmware]] does not have it and/or install some software tool that may be missing in the live system by using the Alpine package manager <code>[[Alpine Package Keeper|apk]]</code>.
* Do a [[Setting up disks manually#Manual partitioning|manual partitioning]] of the hard disk that avoids overwrite of an entire disk.

Examples of such options:

* To install Alpine Linux on an '''entire hard disk''' with optional [[Alpine setup scripts#Environment Variables|environment variables]], proceed to [[#setup-alpine based System Disk Install|setup-alpine based System Disk Install]].
* Use {{ic|setup-disk}} script to complete a [[System Disk Mode|traditional hard disk installation]] on a partition or to [[Dualbooting|dualboot]] or to configure [[Setting up disks manually#RAID|RAID]], [[Setting up disks manually#Encryption|encryption]] or [[Setting up disks manually#LVM|LVM]] for [[#System Disk Mode|"system"]] disk mode or to add a [[#Data Disk Mode|"data"]] mode partition.
* Create a [[Create a Bootable Device#Using setup-bootable|customizable boot media]] i.e a boot device with a writable filesystem for '''[[#Diskless Mode|diskless]]''' or '''[[#Data Disk Mode|data]]''' disk-mode.
* Configure a [[Diskless Mode#Using an internal disk for persistent storage|internal disk for persistent storage]] to save the local configuration state and local package cache for the [[#Diskless Mode|diskless]] system or '''[[#Data Disk Mode|data]]''' disk-mode.

There are many more [[Alpine setup scripts|setup-scripts]] available. All these tools may also be run later to adjust specific configurations. For example, to set up a graphical environment as covered under [[#Post-Installation|Post-Installation]] below.

== Preparing for the installation ==

=== Downloading installation image ===

Installation image files are available in the '''iso''', '''tar.gz''', and '''img.gz''' formats. Download the [https://alpinelinux.org/downloads/ stable release installation image file] for the target computer's architecture with the corresponding <code>sha256</code> checksum and <code>GPG</code> signature files.
{{Tip|Only download the <code>sha256</code> checksum and <code>GPG</code> signature files from the [https://alpinelinux.org/downloads/ official site] and not from mirrors.}}

Now you have three files in the following format:
<pre>
alpine-standard-*.iso
alpine-standard-*.iso.sha256
alpine-standard-*.iso.asc
</pre>

<code>alpine-standard-{{AlpineLatest}}-x86_64.iso</code> is the '''standard''' image file for version '''{{AlpineLatest}}''' and the '''x86_64''' architecture in the '''iso''' format.

=== Verifying downloaded image ===

From Security point of view, verify the downloaded image file for both checksum and GPG signature before proceeding further. The three required utilities i.e <code>sha256</code>, <code>curl</code> and <code>gpg</code> or their equivalents are available in every operating system including Linux, windows, Mac and BSD derivaties.

{{Tip|Ensure that all the three downloaded files remain in the same folder. If not, adjust the commands accordingly.}}

The <code>sha256</code> checksum verifies the integrity of the downloaded image i.e no modifications occurred during download.
{{Cmd|sha256sum -c alpine-*.iso.'''sha256'''}}

The <code>GPG</code> signature verifies the link between the downloaded image to the individual who signed it. Signature verification involves two steps:

Step 1. Download and import the gpg signature from official website
{{Cmd|curl https://alpinelinux.org/keys/ncopa.asc | gpg --import ;}}

Step 2. Verify that the image signature matches with the one downloaded in Step 1.
{{Cmd|gpg --verify alpine-*.iso.'''asc''' alpine-*.'''iso'''}}

=== Preparing installation media ===
{{Seealso|Burning ISOs}}

{{Warning|All data currently on the installation media will be '''erased''', when Alpine Linux installation image is written on it. Correctly identify the device name for the installation media using commands <code>lsblk</code> and <code>blkid</code>.}}
If downloaded image file is in '''img.gz''' format, unzip it using the command {{ic|gunzip alpine-rpi-{{AlpineLatest}}-aarch64.img.gz}} to {{ic|alpine-rpi-{{AlpineLatest}}-aarch64.img}} first before using with {{ic|dd}} command. In Linux {{ic|dd}} command can be used to write image files in both '''iso''' and '''img''' format to the installation media.

If '''tar.gz''' format image file is downloaded, follow the [[Create a Bootable Device#Manually copying Alpine files|instructions]] to create the installation media.

Modify the input file('''if''') of the {{ic|dd}} command according to the name and path to your image file and and the target device i.e output file('''of''') should be a device name '''/dev/sdX''' instead of partition like '''/dev/sdbXY''':{{Cmd|# dd if{{=}}alpine-standard-{{AlpineLatest}}-x86_64.iso of{{=}}/dev/sdX bs{{=}}4M status{{=}}progress; eject /dev/sdX}}

If your version of <code>dd</code> does not support the option "status=progress", remove it. The <code>eject</code> command removes the target device from the system and ensures the write cache is completely flushed.

In Windows and Mac OS, [https://www.balena.io/etcher/ Etcher] can be used to create an installation media.

=== Verifying Installation media ===

After detaching and re-attaching the device, a bit-wise comparison can verify the data written to the device (instead of just data buffered in RAM). If the comparison terminates with an end-of-file error on the .iso file side, all the contents from the image have been written (and re-read) successfully:

{{Cmd|# cmp ~/Downloads/alpine-standard-{{AlpineLatest}}-x86_64.iso /dev/sdX
cmp: EOF on alpine-standard-{{AlpineLatest}}-x86_64.iso</Code>}}

=== Booting Installation Media ===

Insert the [[#Preparing_installation_media|Installation media]] to a proper drive or port of the computer and turn the machine on, or restart it, if already running.
{{Note| To successfully boot and install Alpine Linux, disable [[UEFI#Secure boot|secure boot]] in the BIOS. Once Alpine Linux is installed, this can be [[UEFI_Secure_Boot|enabled]].}}
If the computer does not automatically boot from the desired device, one needs to bring up the boot menu and choose the media to boot from. Depending on the computer, the menu may be accessed by repeatedly pressing a key quickly when booting starts. Some computers require that you press the button ''before'' starting the computer and hold it down while the computer boots. Typical keys are: {{key|F9}}-{{key|F12}}, sometimes {{key|F7}} or {{key|F8}}. If these don't bring up the boot menu, it may be necessary to enter the BIOS configuration and adjust the boot settings, for which typical keys are: {{key|Del}} {{key|F1}} {{key|F2}} {{key|F6}} or {{key|Esc}}.

== Installation Step Details ==

=== Boot Process ===

The boot process of the alpine installation image first copies the entire operating system into the RAM memory, and then starts a complete Alpine Linux system from there. It will initially only provide a basic command line environment that does not depend on reading from any (possibly slow) initial boot media, anymore.

Local log-in is possible as the user <code>root</code>. Initially, the '''root''' user has no password.

At the command prompt, an interactive script named [[Alpine_setup_scripts#setup-alpine|<code>setup-alpine</code>]] is available to configure and install Alpine Linux. The script can be customized by the optional [[Alpine_setup_scripts#Environment_Variables|environment variables]], in case of [[Installation#Data_Disk_Mode|'''"data"''']] or [[Installation#System_Disk_Mode|'''"sys"''']] mode. For e.g {{Codeline|<code>USE_EFI{{=}}1 BOOT_SIZE{{=}}512 setup-alpine</code>}}, sets the disklabel type to gpt, creates 512MB '''/boot''' partition with '''vfat''' filesystem and uses <code>grub</code> as bootloader.

=== Base configuration ===

Launch the Alpine Linux Installation by running the [[Alpine_setup_scripts#setup-alpine|<code>setup-alpine</code>]] script :

{{Cmd|# setup-alpine}}

The question-and-answer dialog of <code>setup-alpine</code> takes care of the base configuration. It sets up a network connection to access Internet to configure the system to boot into one of three different Alpine Linux "disk" modes: [[Installation#Diskless_Mode|'''"diskless"'''(none)]], [[Installation#Data_Disk_Mode|'''"data"''']] or [[Installation#System_Disk_Mode|'''"sys"''']]. If you choose to edit any option, the relevant file is opened in [[BusyBox#vi| '''vi''' editor]] for editing.

{{Tip| If you have access to a wired network, consider using [https://docs.alpinelinux.org/user-handbook/0.1a/Installing/setup_alpine.html#_setup_alpine_q Quick Mode], to complete the base configuration quickly.}}

[[File:Installation-alpine-alpine-setup-3-setup-scripts.png|350px|thumb|right|Example <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> session]]

The <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> script offers the following configuration options:

# '''Keyboard Layout''' (Local keyboard language and usage mode, e.g. ''us'' and variant of ''us-nodeadkeys''.)
# '''Hostname''' (The name for the computer.)
# '''Network ''' (Set up network connection to access Internet.)
#* Available interfaces are: '''eth0''' '''wlan0'''.(List depends on your hardware.)
#* Which one do you want to initialize? (or '?' or 'done') [eth0] (Enter 'done' after configuring '''atleast''' one interface for Internet access.)
#* Do you want to do any manual network configuration? (y/n) [n] (Default uses "DHCP".)
# '''DNS Servers''' (If none of the interfaces configured in previous step uses dhcp, set DNS server. If unsure, leave DNS domain name blank and using <code>[https://quad9.net/ 9.9.9.9 2620:fe::fe]</code> for DNS is typically adequate.)
# '''Root password''' (the password used to login to the root account)
# '''Timezone''' (Optionally display times/dates in your local time zone)
# '''HTTP/FTP Proxy''' (Proxy server to use for accessing the web/ftp. Use "none" for direct connections to websites and FTP servers.)
# '''Mirror''' (From where to download packages. Choose the organization you trust giving your usage patterns to.)
# '''Set up a user''' (Setting up a regular user account)
# '''NTP''' (Network Time Protocol client used for keeping the system clock in sync with a time server. Default is "busybox".)
# '''SSH''' (Secure SHell remote access server. "OpenSSH" is part of the default install image. Use "none" to disable remote login, e.g. on laptops.)
# In most cases, either one of following line(s) is displayed as follows:
#: '''No disks found.''' or ''' Available disks are: sda (128.0 GB JMicron Tech )'''
# '''Disk Mode''' ( A pre-setup of the "diskless" system or base configuration is completed by answering "none" when asked for the following questions.)
#* Which disk(s) would you like to use? (or '?' for help or 'none') '''none'''
#* Enter where to store configs (/media/ or 'none') '''none'''
#* The location of the package cache '''none'''

Base configuration is complete with the above step. Refer to the [[#Alternative courses of action|alternative courses of action]] to proceed further.

=== setup-alpine based System Disk Install ===

<code>setup-alpine</code> script based system disk installation, needs an ''' entire hard disk(s)''' for Alpine Linux and uses a partitioning layout with (/)root partition, /boot partition and a swap partition, where [[Alpine_setup_scripts#Environment_Variables|environment variables]] determine filesystem, size of the boot partition and the bootloader used. If your use case matches the above, at the final step of [[#Base configuration|base configuration]], type the appropriate hard disk '''device name''' instead of '''none'''. If multiple disks are chosen, [[Alpine_setup_scripts#RAID|RAID]] is used.

* At the '''Disk Mode''' stage, '''sda''' or relevant disk(s) must be chosen in the below screen:
** Which disk(s) would you like to use? (or '?' for help or 'none') '''sda'''
** Confirmation for the chosen disk(s) appears. ''The following disk is selected:'' '''sda (128.0 GB JMicron Tech ).'''
{{Warning|Pay close attention to the disk name and size. If you enter '''sys''' in the next step, no further questions will be asked and data on the chosen disk(s) will be overwritten!. Enter {{key|Ctrl}}+{{key|c}} to abort the installation process. Proceed only if you are 100% sure.}}
* How would you like to use it? ('sys', 'data', 'lvm' or '?' for help) '''sys'''

If '''sys''' is chosen, the <code>setup-alpine</code> script will complete the traditional hard-disk installation of Alpine Linux on the chosen disk(s) without further questions. Once the installation is complete, you can skip the next steps and proceed to [[#Reboot|reboot]] the system to boot into the newly installed Alpine Linux and [[Installation#Post-Installation|configure]] further.

=== Custom partitioning ===

[[Setting_up_disks_manually#Manual_partitioning|Manual partitioning]] of the harddisk may be needed to prepare the harddisk for "sys" mode install using [[System Disk Mode|<code>setup-disk</code>]] script and for storing the config file using [[Alpine_local_backup|<code>lbu commit</code>]] and package cache for [[Diskless Mode|Diskless]] and for '''/var''' mount for [[Data Disk Mode|Data disk]] mode installs. Refer [[Setting up disks manually|Setting up disks manually]] page for specific configurations related to [[Setting_up_disks_manually#RAID|RAID]], [[Setting_up_disks_manually#Encryption|encryption]], [[Setting_up_disks_manually#LVM|LVM]], etc...

=== Preparing for the first boot ===

If [[#System_Disk_Mode|System Disk Mode]] of installation was performed, ignore this section and proceed to [[#Reboot|reboot]].

If the new local system was configured to run in "diskless" or "data" mode, and you do not want keep booting from the initial (and possibly read-only) [[Installation#Preparing_installation_media|installation media]], create a [[Create_a_Bootable_Device|customizable boot device]]. Once everything is in place, save your customized configuration with {{ic|lbu commit}} before rebooting.

=== Reboot ===

First, remove the initial installation media from the boot drive, or detach it from the port it's connected to. The system may now be power-cycled or rebooted to confirm everything is working correctly. The relevant commands for this are {{ic|poweroff}} or {{ic|reboot}}. Login into the new system with the root account.

=== Completing the installation ===

The installation script installs only the base operating system. '''No''' applications e.g. web server, mail server, desktop environment, or web browsers are installed.

Please look at [[Installation#Post-Installation|Post-Installation]], for some common things to do after installation.

== Custom Installation Instructions ==


* [[Installation on a headless host]]
* [[Kernels]] ''(kernel selection, e.g. for VMs or RPi)''
* [[How to make a custom ISO image with mkimage]] ''(installation media with its own configuration)''
* [[Directly booting an ISO file]] ''(without flashing it to a disk or device)''
* [[Alpine Linux in a chroot]]
* [[Netboot Alpine Linux using iPXE]]
* [[:Category:Virtualization|Virtualization]]
* [[Using an answerfile with setup-alpine]]

Also see other [[:Category:Installation|Installation category]] pages.

== Post-Installation ==

{{Tip|Alpine Linux packages stay close to the upstream design. Therefore, all upstream documentation about configuring a software package, as well as good configuration guides from other distributions that stay close to upstream, e.g. those in the [https://wiki.archlinux.org/ ArchWiki], or [https://wiki.gentoo.org/wiki/ Gentoo wiki] are to a large degree, also applicable to configuring the software on Alpine Linux, thus can be very useful.}}


* [[Tutorials_and_Howtos#Desktop|Desktop 'How To']] - Alpine Linux as a desktop OS
* [[Tutorials_and_Howtos#Services|Hosting services]] - Such as mail/web/ssh/Firewall/VPN servers
* [[Tutorials_and_Howtos#Virtualization|Virtualization]] guide - For using Alpine Linux as both guest and host
* Guide to [[OpenRC|OpenRC]] - Init system used to configure services
* Create and maintain a [[Rescue disk]]

== See also ==

* [[Tutorials and Howtos]]
* [[Comparison with other distros]] ''(how common things are done on Alpine)''

[[Category:Installation]]

Rescue disk

2026-02-05T05:16:05Z

Prabuanand: moved content from Installation page

A Rescue disk also known as repair disk allows to easily repair an installation that may become faulty due to a package conflict or misconfiguration. To preempt this, a wise precaution would be to prepare and maintain a rescue disk. A rescue disk provides a platform to execute commands using [[chroot]].

== Preparation ==
* Alpine linux [[Installation#Preparing_installation_media|installation media]] could be retained for this purpose.
* A [[Create a Bootable Device|customizable boot device]] for Alpine Linux, e.g. a USB-Stick/CompactFlash/SDCard or SSD/NVMe harddisk based boot device with a writable filesystem i.e, non-iso9660 is also a very good fit for this purpose.

For additional flexibility, rescue disk could be installed on an alternative media (another SD card, USB pendrive, CD-ROM, etc) containing either:-
::(a) a different Alpine Linux version to your workstation's i.e. current-stable vs Edge or vice-versa in case your current impasse is due to a temporary conflict, say, in Edge, it may not manifest in current-stable
::(b) a different distribution
This would be handy as a fallback workstation operating system to investigate the issue

== Maintenance ==

Remember to copy over working {{Path|.config}} files, user guides, etc. from your current system onto the rescue disk beforehand.

{{Tip|Update the rescue disk periodically, particularly if major changes are made to your system.}}

== Troubelshooting ==

== See also ==

* [https://wiki.gentoo.org/wiki/Fix_my_Gentoo Gentoo recovery page]
* [[Alpine rescue|List of useful packages]]
* [https://www.system-rescue.org/ Systemrescue CD]

[[Category:System Administration]]

Talk:Mumble

2026-02-02T04:02:34Z

Prabuanand: suggested about the advantages of moving a page over copying the contents to a new page

== Mumble page created with contents of of Murmur page ==
#Murmur was the old name for the {{Pkg|mumble-server}} package, and '''Mumble''' is the preferred naming of the joint client/server program upstream.
#Expanded Beginning section to describe distinction between the client and server.
#Updated "murmur" package and service to their renamed version: "mumble-server".
#Indicated that installing "murmur" will install "mumble-server" due to the "Provides" directive, etc.
#Added that Alpine Linux v3.21 and earlier still retain the original "murmur" package & service naming.
#Added that the {{Pkg|mumble-server-openrc}} package would be installed automatically on Alpine Linux's default openrc init installations
#Added command prompts and doas.
#Added ''See also'': [[Generating SSL certs with ACF]].
#Style/grammar amendments.
[[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 04:55, 1 February 2026 (UTC)
: Dear [[User:John3-16|John3-16]], Thanks for updating the wiki. For examples like this Murmur->Mumble, you may want to consider '''moving a page''' instead of creating a new page as that will provide an option to preserve all the previous editing history. Moving a page will add also the redirect tag automatically. Thanks again for your contributions. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 04:02, 2 February 2026 (UTC)

Alpine Package Keeper

2026-01-28T09:17:11Z

Prabuanand: added Note template

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file.

{{Note|If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, local packages are upgraded or downgraded back to a repository version.}}

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Alpine Package Keeper

2026-01-28T08:36:01Z

Prabuanand: documented the hash convention in world file and their replacement as per https://gitlab.alpinelinux.org/alpine/apk-tools/-/commit/74b620c

{{TOC right}}
This page documents the Alpine Package Keeper(APK), the package manager in Alpine Linux. Refer to the excellent guide [https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html Working with APK] from Alpine Linux documentation project to learn the basics quickly.

[[Software management#Graphical software manager|Graphical software managers]] can be used for certain basic package management tasks like adding/removing and upgrading packages.

Package management in RAM-based installs like [[Installation#Diskless_Mode|Diskless]] mode and [[Data Disk Mode|Data disk]] mode require [[#Package management in Diskless mode|additional step using lbu]].

== apk v3 ==


{{Pill_clickable||v3 only|green|palegreen|right|Release Notes for Alpine 3.23.0#apk-tools_v3}}
With the release of Alpine Linux [[Release Notes for Alpine 3.23.0|v3.23]], the Alpine package manager has transitioned to [https://gitlab.alpinelinux.org/alpine/apk-tools/-/releases/v3.0.0 apk-tools v3], but the index and package formats are still at v2. apk v3 targets backwards compatibility 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 [[Apk/apkv3 doc diff|available here]] for reference.

== Overview ==

The {{pkg|apk-tools}} provides '''apk''' and it supports the following operations:
{| class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|-
|style="background:black; color:white" colspan=2 align=center |Package installation and removal
|-
|[[#Add a Package|add]] || Add or modify constraints in [[#World|WORLD]] and commit changes
|-
|[[#Remove a Package|del]] || Remove constraints from [[#World|WORLD]] and commit changes
|-
|style="background:black; color:white" colspan=2 align=center |System maintenance
|-
|[[#apk fix|fix ]] || Fix, reinstall or upgrade packages without modifying [[#World|WORLD]]
|-
|[[#Update Package list|update]]|| Update repository indexes
|-
|[[#Upgrade a Running System|upgrade]]|| Install upgrades available from repositories
|-
|[[#Local Cache|cache]] || Manage the local package cache
|-
|style="background:black; color:white" colspan=2 align=center |Querying package information
|-
|[[#apk query|query]] || Query information about packages by various criteria
|-
|[[#Listing installed packages|list]] || List packages matching a pattern or other criteria
|-
|[[#apk dot|dot]] || Render dependencies as [https://graphviz.org/ graphviz] graphs
|-
|[[#apk policy|policy]]|| Show repository policy for packages
|-
|[[#Search for Packages|search]] || Search for packages by name or description
|-
|[[#Information on Packages|info]] || Give detailed information about packages or repositories
|-
|-
|style="background:black; color:white" colspan=2 align=center |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
|-
|style="background:black; color:white" colspan=2 align=center |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|Repositories}}
Official software packages for Alpine Linux have the extension <code>.apk</code>, and are often called "a-packs". Packages in Alpine Linux are organized into [[Repositories|'''repositories''']] and are defined in the {{Path|/etc/apk/repositories}} file. [[Apk spec#Package Format V2|apk v2]] packages are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata.

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

Subpackages related to service files, documentation and shell completions are installed automatically by the package manager using '''auto-install''' rule based on [[APKBUILD_Reference#install_if|install_if]] directive. For example, if {{pkg|zsh}} is already installed, on installing any package with {{pkg|*zsh-completion*}} subpackage, apk automatically installs the associated subpackage. The {{pkg|docs}} meta package for pulling in [[Alpine_Linux:FAQ#Why_don't_I_have_man_pages_or_where_is_the_'man'_command?|all documentation]] works the same way.

Alpine Linux [https://pkgs.alpinelinux.org package database] page shows the list of available subpackages for any 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. {{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>.

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|masking a specific package]]
* '''@tag''' allows apk to use the [[Repositories#Tagged_repository|tagged repository]] for the named package
* '''[<>~=]version''' are used for [[#Package pinning|package pinning]].

The commands {{ic|apk add foo}} and {{ic|apk del bar}} manipulate the desired state by adding or removing packages <code>foo</code>, <code>bar</code> respectively as a dependency constraint in {{Path|/etc/apk/world}}. If the {{Path|/etc/apk/world}} is edited manually, run the command [[#apk fix|apk fix]] to apply the changes.

Every constraint listed in {{Path|/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 [[#ERROR:_unsatisfiable_constraints|commit]] a change to the system that leaves it unbootable.

{{Warning| The option {{ic|force-broken-world}}, will delete world constraints until a solution without conflicts is found to boot. This does not allow installation of packages with unjustifiable dependencies. Using this will likely result in unexpected removal of some packages.}}

== 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. This 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.

== 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|<nowiki># apk add openssh
# apk add openssh openntp vim </nowiki>}}

Packages from a [[Repositories#Tagged repository|tagged repository]] can be installed by adding tags to them:{{cmd|# apk add wireguard-go@testing}}

A specific package can also be [[#Package pinning|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: {{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}}

When a non-repository package is added, a version constraint is added with the package identity hash in the World file. If {{ic|'''--available'''}} option is used with [[#Upgrade a Running System|apk upgrade]] command, such local packages are upgraded or downgraded back to a repository version.

== Remove a Package ==

Use '''del''' to remove a package along with dependencies that are no longer needed.{{cmd|<nowiki># apk del openssh
# apk del openssh openntp vim</nowiki>}}

== Upgrade a Running System ==
{{Seealso|Upgrading Alpine Linux to a new release branch}}
To get the latest security upgrades and bugfixes available for all the installed packages from the [[Repositories#Release_Branches|current release branch]] of a running system, always [[#Update Package list| update the packages list]] before issuing the '''upgrade''' command as shown below:{{cmd|<nowiki># apk update
# apk upgrade </nowiki>}}

Or, combining the same into one single command:{{cmd|# apk -U upgrade}}

To upgrade only ''specific'' packages, use the '''upgrade''' command and specify them: {{cmd|<nowiki># apk update
# apk upgrade busybox</nowiki>}}

When upgrading packages, the package manager may create <var>apk-new</var> files to avoid overwriting configuration files. Once the packages are updated, remember to [[#Handling apk-new files|handle such <var>apk-new<var>]] files.

Here is an example, showing the procedure on a system that has [[Repositories#Using testing repository|testing repository tagged]]:
<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>

=== Upgrading "diskless" and "data" disk mode installs ===

When upgrading packages, the kernel and firmware packages are '''not''' upgraded. Upgrading them requires [[Diskless Mode#update-kernel script|'''update-kernel''']] script.

=== Handling apk-new files ===

apk avoids overwriting configuration files in the {{path|/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 {{path|.apk-new}} appended. When upgrading, you see a message like below: {{Cmd|# 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 the [[Alpine configuration management scripts#update-conf|update-conf]] utility:-

* To list files where changes to configurations from the new packages exist: {{Cmd|# update-conf -l}}
:Paths appear to locations, possibly using double-slash (''"//"'') unix notation, where both the old file and the new file with the {{Path|.apk-new}} extension exist.
* Simply invoking {{ic|update-conf}} will present you with the difference between the two files and offer various choices for dealing with the conflicts.{{Cmd|# update-conf}}
:'''Be very careful''' not to choose ''"u"'' to ''use'' the new file versions for files such as {{Path|passwd}}, {{Path|doas.conf}}, {{Path|shadow}}, {{Path|hosts}}, etc., because otherwise the existing password hashes, user doas settings, etc. '''''would be wiped, and lockouts would occur!''''' Instead, one could choose to compare the new lines (shown with a ''"+"'') with the lines that would be removed (''"-"'') and edit (''"e"'') the files if so wished, or zap (''"z"'') the new version – i.e. delete the new version – if no essential changes are required.
:Therefore, '''update-conf''' does not currently have a merge function set up by default to preserve essential data unlike, say, Debian's '''update-passwd'''.


=== Autoupdate tool for apk ===

Alpine Linux [https://github.com/jirutka/apk-autoupdate tool for automatic updates] is available as {{pkg|apk-autoupdate}} package. It can be used with [[Cron]] to enable unattended, automatic upgrades of packages.

== Package management in Diskless mode ==

Besides using [[#Local Cache|Local Cache]], all package management tasks in [[Diskless Mode|diskless]] and [[Data Disk Mode|Data disk]] mode systems like adding, removing and [[#Upgrading "diskless" and "data" disk mode installs|upgrading]] packages requires running the command: {{Cmd|'''# [[Alpine_local_backup#Committing changes|lbu commit]]'''}}

Only when the above command is run, the changes will take effect on next reboot.

== apk query ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
The query applet is a superset of [[#Information on Packages|info]], [[#Listing installed packages|list]] and [[#Search for Packages|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 [https://pkgs.alpinelinux.org 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: {{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}}

To list packages locally installed that are not longer available in repositories, use {{Cmd|$ apk list --orphaned}}

To browse details of installed package in a "TUI" with:{{Cmd|<nowiki>$ apk list --installed -q | fzf --preview 'apk query {1}'</nowiki>}}

To list subpackages for a package, for e.g {{pkg|util-linux}}:{{Cmd|$ 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 [[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>

== Local Cache ==
{{Seealso|Local APK cache}}
APK can keep a cache of installed packages on a local disk. HDD or [[Installation#System_Disk_Mode|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 Mode|diskless]] installations, [[Local APK cache|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. {{cmd|# apk cache clean}} Or to see what is deleted include the verbose switch: {{cmd|# apk -v cache clean}}

If packages got deleted accidentally from the cache directory, then use the '''download''' command, {{cmd|# 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. {{cmd|# apk cache -v sync}}

== apk dot ==

The dot option renders package dependencies as {{pkg|graphviz}} graphs.[[File:Seatd dependencies.png|800px|center|alt=Seatd dependencies|Seatd dependencies]] Steps to use the dot option is documented below:
# Save the output of apk dot option to a dot file.{{Cmd|$ apk dot seatd > seatd_dependencies.dot}}
# Use <code>dot</code> utility from {{pkg|graphviz}} package to convert the {{Path|seatd_dependencies.dot}} file into a graphical format such as PNG, PDF, or SVG. {{Cmd|$ 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 [[#World|desired system state]].

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

== Configuration file ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
Support for config file for setting default global options has been enabled. The user defined config file {{path|/etc/config/apk}}, if present overrides the {{path|/lib/apk/config}}, intended for distribution default options. To override the default config file name, the environment variable {{ic|APK_CONFIG}} can be used.

The configuration file contains one long option per line as shown here for reference:{{Cat|/etc/config/apk|no-cache
timeout 120}}

The following aliases are available: {{ic|cache}} equals {{ic|cache yes}} and {{ic|no-cache}} equals {{ic|cache no}}.

== Transaction logs ==
{{Pill_clickable||v3 only|green|palegreen|right|Alpine Package Keeper#apk_v3}}
All apk commands which modify the database i.e write transactions are logged to {{Path|/var/log/apk.log}}. To disable the writing of the log file, the configuration option {{ic|logfile}} in the [[#Configuration file|configuration file]] must be set as follows:{{Cat|/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.
|-
| <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}}

=== apk Command Line Parsing ===

==== Use of Single Quotes ====
Advanced use of '''apk''' could require the use of single quotes around its argument (e.g. {{ic|apk <var>add</var> '<var>argument</var>'}}) when certain characters are being employed, since Unix shells – including the default '''sh''' ('''ash'''/'''busybox''') shell, '''bash''' or '''zsh'''/'''fish''' – will attempt to interpret the argument if it is not enveloped in single quotes:-
* {{ic|<}} in an argument would be unintendedly interpreted as "input redirection"; {{ic|asterisk<1.6.1}} without quotes would prompt the shell to attempt to read from an {{Path|asterisk}} file; similarly, {{ic|>}} would be interpreted unintendedly as "output redirection"
* {{ic|~}} would attempt to expand the argument to include the user’s home directory path
* {{ic|*}}, {{ic|?}}, {{ic|[0-9]}} without single quotes around the argument could cause globbing, meaning that the shell would try to expand the package name using the meaning of those characters ({{ic|*}} meaning any string of alphanumeric characters, for example) and then try to apply '''apk''' to any ''file'' fitting that name in the current working directory as an unintended interpretation
* {{ic|!}} in a '''bash''' or '''zsh''' shell without using quotes would be interpreted as "history expansion" as opposed to [[#Package_masking|"negate installation"]], as intended. Note that, if using '''ash''' (Alpine Linux’s default), the lack of single quotes is not problematic there as that shell does not support history expansion. History expansion is ''disabled by default'' in '''fish'''.
Therefore, the use of single quotes is typically required in various shells to enclose the package name/version, with or with any '!' symbol, to be handed directly to the '''apk''' tool so that it is not attempted to be interpreted by the shell.

=== Package pinning ===
{{Seealso|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 [[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.}}

For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:{{cmd|<nowiki># apk add asterisk=1.6.0.21-r0</nowiki>}}
or – note the need for [[#Use_of_Single_Quotes|single quotes]]:{{cmd|# apk add 'asterisk<1.6.1'}}

To upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level:{{cmd|# apk upgrade}}

To later upgrade to the current version, and ensure that 1.6.1 is the minimum version used. {{cmd|# 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: {{cmd|<nowiki># apk add 'asterisk=~1.6'</nowiki>}}

==== Holding a specific package back ====
See [[#Package pinning|Package pinning]]

=== Package masking ===

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'':
{{Cmd|# 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 exclamation mark (!) is often used in logic and IT to express negation.

As [[#Use_of_Single_Quotes|detailed above]], be sure to employ the single quotes (') if using certain shells ''other than'' the unaffected '''ash''' shell so as to avoid an unintended interpretation by the shell interpreter.

The package then appears negated in ''world'':
{{Cat|/etc/apk/world|fon
!foo
fop}}

==== Unmasking a specific package ====

Simply install it ''explicitly'' using '''apk'''. Say:
{{Cmd|# apk add foo}}
Uninstall it afterwards, if not required.
Alternatively, delete the line in {{Path|/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:

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

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

== 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: {{ic|# 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.

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

The above error message may occur in [[Edge|Edge]] branch in certain other situations, even if all the necessary [[Repositories|repositories]] are enabled. Temporary non-availability of the packages from the repositories can occur, when software packages are [https://build.alpinelinux.org/ 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 [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 [[Repositories#Edge|Edge]] package(s) also installed. One resolution is to consider upgrading {{pkg|apk-tools}}. If edge/main is already [[Repositories#Tagged repository|tagged]] as ''@edgemain'' in your {{Path|/etc/apk/repositories}} file, then try: {{Cmd|# 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:
{{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.

=== ERROR: unable to select packages: breaks: world ===

{{Cmd|<nowiki># 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]</nowiki>}}

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

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

On issuing a command to remove a package for eg: {{ic|# 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 {{ic|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 ==

* [https://git.alpinelinux.org/apk-tools/tree/doc/apk.8.scd Manual for apk(8)]
* [https://git.alpinelinux.org/apk-tools/tree/doc/apk-world.5.scd Manual for apk-world(5)]
* [https://pkgs.alpinelinux.org Official web interface for packages]
* [[Software management]]
* [https://ariadne.space/2021/04/24/why-apktools-is-different-than.html Why apk-tools is different than other package managers]
* [https://ariadne.space/2021/10/30/spelunking-through-the-apktools-dependency.html 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]
* [https://www.cyberciti.biz/faq/10-alpine-linux-apk-command-examples/ 10 Alpine Linux apk Command Examples]
[[Category:Package Manager]]
[[Category:System_Administration]]

Software management

2026-01-25T13:49:18Z

Prabuanand: added Accuracy template

This page documents various ways to [[#Running glibc programs|run software compiled with glibc]] and to manage software using [[#Graphical software manager|graphical software managers]] in Alpine Linux. There are pages elsewhere regarding compiling [[Compile software from source|software from source]] and for creating a [[Custom Kernel|custom kernel]].

== Alpine package keeper ==
{{Main|Alpine Package Keeper}}
The official package manager in Alpine Linux, [[Alpine Package Keeper|Alpine Package Keeper(apk)]], is a ''cli'' tool. [[Comparison_with_other_distros#Comparison_chart/Rosetta_Stone|Rosetta stone]] shows how standard package management tasks are done in Alpine Linux compared to other popular distributions.

== Graphical software manager ==

The following graphical tools are available to manage official software packages from Alpine Linux [[Repositories|repositories]] and [[#Flatpak|flatpaks]] instead of using the [[#Alpine Package Keeper|cli-based apk tool]].

=== GNOME software ===

[[GNOME#Configuration|GNOME software]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

=== KDE Discover ===

[[KDE#Discover|KDE Discover]] can be used as a GUI front end for apk to manage official software packages and flatpaks.

== AppImage ==
{{Main|AppImage}}
{{Accuracy|Many AppImages does not work compared to Flatpaks.|section=AppImage}}
AppImages are by far the easiest method for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. Refer to the [[AppImage]] page for prerequisites and for detailed instructions to run them in Alpine Linux.

== Flatpak ==
{{Main|Flatpak}}

[[Flatpak#Installing_Flatpak|Flatpak]] is an alternative to [[AppImage|AppImages]] for running programs that are not available in the official Alpine Linux [[Repositories|repositories]]. To use flatpaks, ensure that the [[Flatpak#Installing_Flatpak|Flathub repository]] is enabled.

== Coldbrew ==

'''Coldbrew''' is a package manager that can install Alpine Linux aports Edge packages without needing root access, somewhat similar to '''brew'''. This is particularly useful on immutable operating systems such as with [https://postmarketos.org/blog/2025/10/12/pmOS-update-2025-09/#immutable-postmarketos PostmarketOS's duranium image]. '''Coldbrew''' is available in Alpine Linux Edge testing repository as of January 2026; the testing repository is [[Repositories#Using_testing_repository|recommended to be tagged]] if installing '''coldbrew''' on any supported Alpine Linux release.

'''Coldbrew''' replaces the [https://github.com/kcxt/iced '''iced'''] package on Alpine Linux, which used the {{Pkg|mkosi-sandbox}}; packages run inside a chroot using '''bubblewrap''' instead. They have access to the home directory, but have only controlled access to all other files through explicit bind mounts. Packages installed using '''coldbrew''' are referred to as tools. See [https://gitlab.postmarketos.org/postmarketOS/coldbrew further details upstream].

To install '''coldbrew''':
{{Cmd|$ doas apk add coldbrew@testing}}

To install a tool to be run by '''coldbrew''', say, {{Pkg|corepad}}:
{{Cmd|$ coldbrew install corepad}}

Note that even though the output ends...

Installed binary /usr/bin/corepad

...the path being referred to exists within a new mount namespace using bind mounts in the '''bubblewrap''' sandbox.

A wrapper program is installed to {{Path|~/.local/bin}} on Alpine Linux.

To run the tool under '''coldbrew''':
{{Cmd|$ coldbrew run corepad}}

To remove the tool:
{{Cmd|$ coldbrew remove corepad}}

All installed tools can be listed through the {{ic|$ coldbrew ls}} command.

== Running glibc programs ==

If you want to run [https://www.gnu.org/software/libc/ glibc] programs in Alpine Linux, there are a few ways of doing so.

For simpler binaries, you can install [[#gcompat|gcompat]], which is a compatibility layer; or you could do it the easy way and use [[#Flatpak|Flatpaks]] or [[#AppImage|AppImages]]. See [[#Containers|containers]] or the [[#Chroot|chroot]] section for ways to run glibc programs, including graphical ones such as {{ic|VSCode}}, {{ic|google-chrome}}, {{ic|obsidian}}, etc.

=== gcompat ===

[https://git.adelielinux.org/adelie/gcompat gcompat] is a library that provides glibc-compatible APIs for use on musl libc systems such as Alpine Linux. To install, issue the command: {{cmd|$ doas apk add {{pkg|gcompat}}}}
After that, you run your binaries as normally.

For an usage example, refer to the [[Firefox#DRM_content_using_Widevine_workaround|Firefox]] page where gcompat is used to run the glibc-compiled Widevine binary.

== Chroot ==
{{Main|Chroot}}

An option that is easier to generalize to other glibc applications is to install a glibc-based distribution into a chroot. You can then either chroot into it, or use a symlink and some configuration to make its glibc (and associated libraries) usable from Alpine.

{{Tip|The most reliable way to enter a chroot is to use the [[Chroot#Enter_chroot|start-chroot]] script.}}

After setting up a chroot using any of the methods described below, the loader can be set up in Alpine as follows (these instructions are for a Debian chroot in {{Path|/var/chroots/debian}}, on x86_64, but can be adapted to other systems by using the appropriate paths):

{{cmd|$ doas mkdir -p /lib64
$ doas ln -s /var/chroots/debian/lib/x86_64-linux-gnu/ld-2.33.so /lib64
$ doas printf '/var/chroots/debian/lib/x86_64-linux-gnu\n/var/chroots/debian/usr/lib/x86_64-linux-gnu\n' > /etc/ld.so.conf
$ doas /var/chroots/debian/sbin/ldconfig}}

=== Gentoo Linux ===

Select a ''stage3'' from [https://www.gentoo.org/downloads/ here] and the ''portage'' latest from [https://www.gentoo.org/downloads/mirrors/ here] at gentoo/snapshots/portage-latest.tar.xz.

First,{{cmd|$ doas apk add {{pkg|xz}}}}

Enter the chroot:
{{cmd|$ doas mkdir ~/chroot
$ doas cd ~/chroot
$ doas tar -xvf stage3-*.tar.xz
$ doas tar -xvf portage-latest.tar.xz
$ doas mv portage usr
$ doas mount --bind /dev dev
$ doas mount --bind /sys sys
$ doas mount -t proc proc proc
$ doas cp /etc/resolv.conf etc
$ doas chroot . /bin/bash}}

And voilà, you have your working Gentoo chroot! 

You can now take a look at [https://wiki.gentoo.org/wiki/Handbook:Main_Page Gentoo's Handbook] to find out how you can configure and install your system, or simply extract/copy the program that you need to run in your chroot enviroment, and then execute it.

Here is a wrapper script that is similar to {{ic|arch-chroot}} when you frequently reuse this chroot. Also, create an account with the same username as host current user to the chroot, or make changes to the {{ic|userspec}} option to chroot line:

{{Cat|gentoo-chroot.sh|<nowiki>#!/bin/bash
CHROOT_PATH="/home/$USER/chroot"
cd $CHROOT_PATH
mount | grep $CHROOT_PATH/dev || doas mount --bind /dev dev
mount | grep $CHROOT_PATH/sys || doas mount --bind /sys sys
mount | grep $CHROOT_PATH/proc || doas mount -t proc proc proc
cp /etc/resolv.conf etc
doas chroot --userspec=$USER:users . /bin/bash
echo "You must manually unmount $CHROOT_PATH/dev, $CHROOT_PATH/sys, $CHROOT_PATH/proc."
</nowiki>
}}

Do {{ic|$ chmod +x gentoo-chroot.sh}} to make it executable.

=== Arch Linux ===

{{Seealso|Installing ArchLinux inside an Alpine chroot}}
Either use '''pacstrap''' (included with the arch-install-scripts package) or an Arch bootstrap image:

{{cmd|$ doas apk add {{pkg|arch-install-scripts}}
$ mkdir ~/chroot && cd ~/chroot
$ curl -O https://mirrors.edge.kernel.org/archlinux/iso/latest/archlinux-bootstrap-x86_64.tar.zst
$ doas tar -x --zstd -f archlinux-bootstrap-x86_64.tar.zst && rm archlinux-bootstrap-x86_64.tar.zst
$ doas sed -i '/evowise/s/^#//' root.x86_64/etc/pacman.d/mirrorlist
$ doas sed -i '/CheckSpace/s/^/#/' root.x86_64/etc/pacman.conf
$ doas arch-chroot root.x86_64
[chroot]# pacman-key --init
[chroot]# pacman-key --populate archlinux}}

Once that is done, update the system and install the desired package(s) (denoted by ''"foo"'' in this example):

{{cmd|[chroot]# pacman -Syu <var>foo</var>}}

=== Debian ===

Alpine Linux provides the {{pkg|debootstrap}} package to create the Debian chroot. Here are the steps: {{cmd|$ doas apk add debootstrap
$ doas mkdir -p /var/chroots/debian
$ doas debootstrap --arch amd64 stable /var/chroots/debian/ https://deb.debian.org/debian}}

The {{ic|--arch}} is optional, depending on your needs.

For updating the chroot, or for installing packages and their dependencies using {{ic|apt-get}}, mount it, and then login as root:
{{cmd|$ doas mount --bind /dev /var/chroots/debian/dev
$ doas mount --bind /proc /var/chroots/debian/proc
$ doas mount --bind /dev/pts /var/chroots/debian/dev/pts
$ doas chroot /var/chroots/debian /bin/bash
[chroot]# apt update && apt upgrade}}

After installing the necessary applications and whatever else you might do, exit the chroot:
{{cmd|[chroot]# exit}}

Then, unmount the binds for /dev/pts, dev and proc to avoid issues:
{{cmd|$ doas umount /var/chroots/debian/dev/pts
$ doas umount /var/chroots/debian/dev
$ doas umount /var/chroots/debian/proc}}

== Containers ==

=== Distrobox + Podman ===

[[Distrobox]], combined with [[Podman|podman]] container running in rootless mode, allows to easily run [[Distrobox#Running_graphical_programs|glibc-compiled graphical programs]]. This will not require root privileges once set up.

=== Bubblewrap + Chroot ===

{{ic|glibc}} and {{ic|glibcX11}} shell aliases are defined interactively using bwrap to create a container with [[Bubblewrap]], using a [[#Debian|Debian chroot]] as its content. It's not just a chroot anymore: it's a bubblewrap-powered isolated environment. This allows for easily running graphical programs and does not require root privileges once installed.

[[Install]] the {{pkg|bubblewrap}} package.

Set up [[#Debian|Debian chroot]] at {{path|/var/chroots/debian}} and install necessary glibc applications using {{ic|apt-get}}.

Create a {{ic|glibc}} alias using bwrap in the Alpine Linux host in order to start applications from the [[#Debian|Debian chroot]]:
{{cmd|$ alias glibc{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group"}}

To run programs that use X11/Xorg, you can use:
{{cmd|$ alias glibcX11{{=}}"LANG{{=}}en_US.UTF-8 bwrap --bind /var/chroots/debian / --dev-bind /dev /dev --proc /proc --bind /sys /sys --bind /run /run --bind /home /home --ro-bind /etc/resolv.conf /etc/resolv.conf --ro-bind /etc/passwd /etc/passwd --ro-bind /etc/group /etc/group --bind /tmp/.X11-unix/X0 /tmp/.X11-unix/X0 --setenv DISPLAY :0"}}

In this case, you might need to use {{ic|xhost}} on the Alpine Linux host in order to allow local connections. For example:{{cmd|# xhost + local:}}

Now we can invoke glibc-built binaries using the alias from the Alpine Linux host, as follows:
{{cmd|$ glibc ./binary}} or {{cmd|$ glibcX11 ./binary}}

When a [[Wayland]] desktop such as [[Sway]] runs without XWayland on the Alpine Linux host, Electron apps need to be started with Ozone Wayland support:

* For VS Code (note the use of the {{ic|code}} command):
{{cmd|<nowiki>glibc code --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

* For Google Chrome, etc:
{{cmd|<nowiki>glibc google-chrome --enable-features=UseOzonePlatform --ozone-platform=wayland</nowiki>}}

The flags enforce Wayland rendering, thus avoiding XWayland and improving display, particularly if fractional scaling is also used.

== See also ==

* [[Alpine Package Keeper]]
* [[Installing ArchLinux inside an Alpine chroot]]
* [[Compile software from source]]
* [[Kernels]]

[[Category:Package Manager]] [[Category:Development]]

Talk:Software management

2026-01-25T13:43:03Z

Prabuanand: /* AppImage */ new section

Please add the following if pertinent:
https://github.com/sgerrand/alpine-pkg-glibc/

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Mekineer|Mekineer]] ([[User talk:Mekineer|{{int:talkpagelinktext}}]] • [[Special:Contributions/Mekineer|{{int:contribslink}}]]) 11:04, 26 February 2024‎
----

I thought about the MegaCli wrapper.
It should be possible to make it read the name it was called by and then launch the respective program
(i.e. symlink any to-be-wrapped command to /var/lib/glibcstuff ...)

that way you get along with one wrapper script and symlinks to it in /usr/bin.

Another thing I couldnt figure is if it's important to use all 32bit versions?

And the download links for archlinux are not working because they forward wget to an https url.
maybe this is some limitation in the default wget version. If i figure it out i'll do updates on this.

this is my /usr/bin/MegaCli now, using a minimal Debian install in /debian.

<nowiki>
#!/bin/bash

KEYS="kernel.grsecurity.chroot_caps kernel.grsecurity.chroot_deny_chmod \
kernel.grsecurity.chroot_deny_chroot kernel.grsecurity.chroot_deny_fchdir \
kernel.grsecurity.chroot_deny_mknod kernel.grsecurity.chroot_deny_mount \
kernel.grsecurity.chroot_deny_pivot kernel.grsecurity.chroot_deny_shmat \
kernel.grsecurity.chroot_deny_sysctl kernel.grsecurity.chroot_deny_unix \
kernel.grsecurity.chroot_enforce_chdir kernel.grsecurity.chroot_findtask \
kernel.grsecurity.chroot_restrict_nice"

for key in $KEYS ; do
sysctl -w ${key}=0 1>/dev/null
done

export CHROOT=/debian
user=$(whoami)
if [ "$user" != "root" ];then
echo "This script needs root access"
exit
fi
mount -t proc proc $CHROOT/proc/
mount --bind /dev/ $CHROOT/dev/
mount --bind /sys/ $CHROOT/sys/
#we may need dev and maybe proc too to use this program
chroot $CHROOT /opt/MegaRAID/MegaCli/MegaCli $@
umount $CHROOT/proc
umount $CHROOT/dev
umount $CHROOT/sys</nowiki>

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Darkfader|Darkfader]] ([[User talk:Darkfader|{{int:talkpagelinktext}}]] • [[Special:Contributions/Darkfader|{{int:contribslink}}]]) 15:32, 11 July 2014‎

----

If you know how to relax grsecurity without using vanilla on Gentoo to allow PAM to not trigger a postinst error, you should edit the Gentoo section.

— Preceding [[Help:Signature|unsigned]] comment added by [[User:Orson Teodoro|Orson Teodoro]] ([[User talk:Orson Teodoro|{{int:talkpagelinktext}}]] • [[Special:Contributions/Orson Teodoro|{{int:contribslink}}]]) 13:12, 3 February 2018‎

I'm unsure, if it's OK to add the following to page: will leave it here for reference:
Here are the steps to run vscode, If running [[Sway]] on Alpine Linux.
# From your Alpine Linux host, download Visual Studio Code from the official website https://code.visualstudio.com/docs/?dv=linux64_deb to your home folder.
# Install the vscode as follows: {{Cmd|$ distrobox enter my-debian --sudo apt-get install -f /home/<Username>/code_<version_number>_amd64.deb}}
# Run vscode as follows: {{Cmd|<nowiki>$ distrobox enter my-debian -- code --ozone-platform=wayland</nowiki>}}
--[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 11:10, 2 June 2025 (UTC)

== AppImage ==

Dear [[User:John3-16|John3-16]], your [https://wiki.alpinelinux.org/w/index.php?title=Software_management&diff=prev&oldid=31876 edit] changed the preferred method of running glibc applications from [[Flatpak]] to [[AppImage]]. Flathub is a known repository with a lot of applications that is guaranteed to work in Alpine Linux. I'm not aware of an equivalent reliable i.e trusted source for AppImages that is guaranteed to work in Alpine Linux.
I tested a few from http://www.appimagehub.com and many did not work.

Please reconsider the above edit and consider restoring the Flatpak suggestion, until AppImages consistently work in Alpine Linux. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 13:43, 25 January 2026 (UTC)

AppImage

2026-01-25T13:12:24Z

Prabuanand: removed the external website

{{Draft|work in progress}}

[https://appimage.org AppImages] allow a simple executable-like experience, but the problem is that many AppImages require glibc, and Alpine Linux uses [[musl]].

== Installation ==

First you need {{Pkg|fuse}} for AppImages to work; then, modprobe it.
{{Cmd|# apk add fuse

<nowiki>#</nowiki> modprobe fuse}}
Optional, but recommended: install {{pkg|gcompat}} package for [[Software_management#Running_glibc_programs|glibc compatibility]].
{{Cmd|# apk add gcompat}}

== Download AppImage ==

Download your AppImage to the user's directory. The {{Path|~/.local/bin}} location is suitable, further to [https://specifications.freedesktop.org/basedir/latest/#variables XDG Base Directory Specifications]. {{Path|~/bin}} is another common location. {{Warning|Downloading or launching AppImages as root is a '''security risk''' and should be avoided.}}

Create the above mentioned directory, if necessary. It is good practice to ensure that the location for your AppImages appears in the user's {{Path|$PATH}} for executables so that the AppImages could be launched from a shell (aka 'terminal') without needing to specify their path. To check, from a user's prompt: {{Cmd|$ echo $PATH}}

For AppImages to appear in an app launcher, additionally, a {{Path|.desktop}} file with the AppImage's name would need to be created or found upstream and used if licence permits, placing it in {{Path|~/.local/share/applications}}.

== Usage ==

You have to make the downloaded AppImage executable so that you can launch it: {{Cmd|$ chmod +x <var>Example</var>.AppImage}}

To execute it, for example, when the current working directory of your user prompt is the directory where the AppImage is stored, then you can instruct your shell that the AppImage to be launched is located in that same directory by using the prefix {{ic|./}}:{{Cmd|$ ./<var>Example</var>.AppImage}}

If the AppImage was stored in the user's {{Path|$PATH}} for executables, neither navigating to the shell to use the {{ic|./}} prefix nor stating the path as a prefix would be necessary to execute it:{{Cmd|$ <var>Example</var>.AppImage}}

== See also ==

[[Category:Software]]

AppImage

2026-01-25T13:07:59Z

Prabuanand: added warning, link to external site with appimages built for musl

Zero-To-Awall

2026-01-24T17:06:03Z

Prabuanand: added wikilink

This [https://git.alpinelinux.org/awall/about/ Alpine Wall] howto is aimed at users with no or little experience with iptables and other firewall framework. [[How-To Alpine Wall]] page is aimed at users familiar with shorewall and [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide] is the official source for details about the syntax.

== Base policies ==

Be aware that all configuration files are stored as JSON files. JSON is not a human friendly standard, for instance it does not support comments so you will have to move them outside of the json structure.

Beginners should use a decent text editor with JSON highlight support which will make your life easier. Recent versions of Alpine Wall support using yaml instead of json but this is out of scope of this howto.

Creating zones depends on the function of your firewall. Is it installed on a endpoint (server) or will it act as a router and filter/forward.

For this howto we assume you are going to setup a router and use NAT to forward services (ports) to different hosts on your network.

For each interface on router we will setup a zone and assign it a zone name. We do this by creating the following file: /etc/awall/private/base.json
<pre>
{
"description": "Base zones and policies",

"zone": {
"WAN": { "iface": "eth0" },
"LAN": { "iface": "eth1" },
"VPN": { "iface": "tun+" }
},

"policy": [
{ "in": "VPN", "action": "accept" },
{ "out": "VPN", "action": "accept" },
{ "in": "LAN", "action": "accept" },
{ "out": "LAN", "action": "accept" },
{ "in": "_fw", "action": "accept" },
{ "in": "_fw", "out": "WAN" , "action": "accept" },
{ "in": "WAN", "action": "drop" }
],

"snat": [ { "out": "WAN" } ],

"clamp-mss": [ { "out": "WAN" } ]

}
</pre>

Lets break this down into sections

=== description ===

The description is here just for reference and will be used by <code>awall list</code>.

=== zone ===

This is where our zones are defined. Zones are defined based on a interface and assigned a name to be used in your policies.
In our example you can see that we have two real interfaces eth0 and eth1 and one or more virtual interfaces tun+ (the plus sign stands for any digit like tun0 tun1 and so on). In case you are installing awall on an endpoint (a server) then you will most probably not have the eth1 interfaces and can leave it out. In our example the tun+ interface is added as it is very commonly used like when using openvpn.

=== policy ===

These are our main policies. It will tell our firewall what to do with when a packet enters or leaves from one of the zones (interfaces).
You will notice a special <code>_fw</code> name which means the internal firewall (the local machine) which means the packet does not leave the firewall via another interface but should be send to one of the local services.
You can see that we by default do not filter any package coming from or going to our VPN zone/interface. You could instead change the default action to drop all packets and create separate policies to allow specific traffic but this is out of the scope of this howto.

=== snat ===

Apply source nat for outgoing packets. This is only needed if your firewall acts as a router and traffic behind the router needs a modified source address (translate from local ip to public ip).

=== clamp-mss ===

https://github.com/alpinelinux/awall#mss-clamping-rules

== Service policies ==

Now that we have the base firewall in place we can start to define specific policies so our services will be reachable from the outside world.\
By default we are blocking all traffic coming in on our WAN interface (action=drop). The first thing we want to open is our SSH port/service. To do this we need to create a new policy inside the "optional" directory.
You could be wondering why the optional name, thats is because mandatory policies are stored in <code>/usr/share/awall/mandatory</code> and not to be touched and our optional policies can be enabled/disabled on the run.

=== SSH service ===

To add our SSH policies we create a new file: /etc/awall/optional/ssh.json
<pre>
{
"description": "Allow rate-limited SSH on WAN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "ssh",
"action": "accept",
"conn-limit": { "count": 3, "interval": 20 }
}
]
}
</pre>

==== description ====

This is similar for any policy

==== Filter ====

This is the actual filter that is currently set to drop the packets arriving or leaving the interface.

===== in =====

The interface the packets arrive on, in this case its the WAN interface.

===== out =====

The interface the packets leave on, in this case its _fw which means it does not leave our firewall/device and is targeted at our local SSH service.

===== service =====

This is the service definition provided by awall or a custom service which we will discuss later on.

===== action =====

The action on the packet, this inverts the default action of drop and accepts the packets.

===== conn-limit =====

This is a special feature of our firewall/iptables to allow only a certain amount of packets in a certain amount of time. For more information please check our awall manual.

=== SSH to another Host ===

edit the following file: /etc/awall/optional/ssh-to-hostname.json

<pre>
{

"description": "Forward SSH to hostname",

"filter": [
{
"in": "WAN",
"service": { "proto": "tcp", "port": 22001 },
"action": "accept",
"conn-limit": { "count": 3, "interval": 20 }
}
],

"dnat": [
{
"in": "WAN",
"dest": "$SERVER",
"service": { "proto": "tcp", "port": 22001 },
"to-port": "22"
}
]
}
</pre>

Lets discuss the differences between this policy and the previous SSH policy.

==== Filter ====

===== service =====

Because port 22 is already in use by our own firewall, we need to listen on a different port. In this example we listen on port 22001.
And because we are not using the default port 22 we need to define our own service specification.

==== dnat ====

Also known as destination NAT.

===== dest =====

The destination the packet will be forwarded to. In this case we are using a variable named $HOSTNAME. Anywhere in your policies you can define your own variables and use them.
In our case we have used a file in /etc/awall/private/aliases.json more on this topic later on.

===== to-port =====

This is the destination target port number. The packet will be forwarded from 22001 to 22 on the $hostname

=== OpenVPN Service ===

This is the most generic config available. It does nothing more then opening port(s) defined for our openvpn service in {{path|/etc/awall/private/custom-services.json}}

<pre>
{

"description": "Allow local OpenVPN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "openvpn",
"action": "accept"
}
]
}

</pre>

=== Allow ping on WAN ===

Allow rate-limited ping on WAN. Which has the same kind of flow limit as our previous SSH policy.

<pre>
{

"description": "Allow rate-limited ping on WAN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "ping",
"action": "accept",
"flow-limit": { "count": 10, "interval": 6 }
}
]
}
</pre>

== Using aliases and custom services ==

=== Aliases ===

To make life easier when your firewall rules increase, it can be nice to map specific hosts to names.
Awall supports something called [https://github.com/alpinelinux/awall#variable-expansion variable expansion] which is a mapping between a value and a variable.
When you have many devices behind your firewall/router, your policies can be harder to read. Also when one of your devices IP address change you will have to update all of your policies.
With awalls variables you can assign the ip address of a device to a variable name. Edit the following file: <code>/etc/awall/private/aliases.json</code>
<pre>
{
"description": "Hostname aliases",

"variable": {
"PRINTER": "192.168.1.1",
"SERVER": "192.168.1.2"
}

}
</pre>

Look in the example above where $SERVER is used to forward port 22001 to port 22.

NOTE: You are not limited to assigning only IP addresses to variables. You can use it however you like. More information can be found in the awall manual.

=== Custom services ===

Awall includes a predefined list of [https://raw.githubusercontent.com/alpinelinux/awall/master/mandatory/services.json services]. If the service you try to define in your policy does not exist in awalls services list you can define services yourself.

Create the file: {{path|/etc/awall/private/custom-services.json}}

<pre>
{
"service": {

"mqtt": [
{ "proto": "udp", "port": 1883 },
{ "proto": "tcp", "port": 1883 }
],

"openvpn": [
{ "proto": "udp", "port": 1194 },
{ "proto": "tcp", "port": 1194 }
]

}
}
</pre>

NOTE: although you are free to name your policy files however you want, you cannot name this file <code>services.json</code> because this policy name is already in use by the included services.json of awall.

== Using our policies ==

You should now have two directories in your awall config directory named optional and private with multiple json files. The biggest difference between these two directories is the ability to enable and disable policies located in the optional directory. When you enable a policy by using <code>awall enable policy-name</code> awall will generate a symlink in your awall config directory and will automatically load them when you activate the firewall. To be able to also use the files in the private directory we will need to include them in one of our optional policies. You can name the file however you like as long it doesn't conflict with existing policies names (including the ones in private directory and awall's system policies). Example names would be hostname.json main.json firewall.json. For this example we will use main.json.

Create the file: <code>/etc/awall/optional/main.json</code>
<pre>
{
"description": "Main firewall",

"import": [ "base", "aliases", "custom-services" ]

}
</pre>

Contents of your awall directory:
<pre>
awall
│
├── optional
│ ├── main.json
│ ├── openvpn.json
│ ├── ssh-to-hostname.json
│ └── ssh.json
└── private
 ├── aliases.json
 ├── base.json
 └── custom-services.json
</pre>

=== Enabling optional policies ===

Lets enable our created policies. First we list them by running <code>awall list</code> which would show something like:
<pre>
openvpn disabled Allow local OpenVPN
main disabled Main firewall
ping disabled Allow rate-limited ping on WAN
ssh disabled Allow rate-limited SSH on WAN
ssh-to-hostname disabled Forward SSH to hostname
</pre>

Each of these needs to be enabled:
<pre>
awall enable openvpn
awall enable main
awall enable ping
awall enable ssh
awall enable ssh-to-hostname
</pre>

The contents of your awall directory should now look like:
<pre>
awall/
├── main.json -> ./optional/main.json
├── openvpn.json -> ./optional/openvpn.json
├── optional
│ ├── main.json
│ ├── openvpn.json
│ ├── ping.json
│ ├── ssh-to-hostname.json
│ └── ssh.json
├── ping.json -> ./optional/ping.json
├── private
│ ├── aliases.json
│ ├── base.json
│ └── custom-services.json
├── ssh-to-hostname.json -> ./optional/ssh-to-hostname.json
└── ssh.json -> ./optional/ssh.json

2 directories, 13 files
</pre>

=== Testing policies ===

<code>awall translate --verify</code>

if everything goes well the output should be null.

=== Activating the firewall ===

Now that all our policies are verified for proper json we can activate it.

<code>awall activate</code>

This will load the firewall rules and show you a message to confirm. If by accident you made a mistake and lock yourself out you just have to wait for awall to disable itself again.

== Finishing up ==

=== Activating firewall rules at boot ===

When awall has been properly activated it will generate a file with all iptables rules which iptables will read when its is started via openrc.
Make sure you have added iptables to an openrc runlevel. If using snat, also enable ipset for the masquerade set.

<code>rc-update add iptables</code>

<code>rc-update add ipset</code>

=== Allow IPv4 forwarding ===

To allow iptables to forward packets from one zone to the other we need to enable this at the iptables level.

==== On the fly ====

To enable it on the fly:
<code>sysctl -w net.ipv4.ip_forward=1</code>

==== Enable within iptables tools (at boot) ====

Add the following to:
<code>/etc/conf.d/iptables</code>
<pre>
# Enable/disable IPv4 forwarding with the rules
IPFORWARD="yes"
</pre>

== See also ==
* [[How-To Alpine Wall]]
* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
[[Category:Firewall]]

How-To Alpine Wall

2026-01-24T16:56:34Z

Prabuanand: added wikilink and simplified introduction

This page shows how to configure Alpine Wall(awall) as compared to {{pkg|Shorewall}} firewall. This comparison is meant to help readers who are familiar with Shorewall learn AWall. Awall users should follow the AWall configuration examples. Use the Shorewall examples as contextual references, or ignore them, if unfamiliar with Shorewall.

[[Zero-To-Awall]] howto page is meant for users with no firewall experience and [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide] is the official source for details about the syntax.

== Installation ==

Install the {{pkg|awall}} package by running the following command:{{cmd|# apk add iptables awall}}

Note that awall requires {{pkg|iptables}} but works with both backends [[nftables]] and legacy [[iptables]]. It does not interact with nftables directly.

== Configuration ==

The easier method for performing initial steps for running awall: {{cmd|# awall activate}}
The above command has special handling for the first run, when firewall is not yet enabled in the kernel. It performs the below manual steps and also updates the default runlevel and files in {{Path|/etc/conf.d}}

Use the below commands for performing initial setup manually.
* To update /etc/iptables: {{cmd|# awall translate}}
* To start the [[OpenRC]] services for iptables and load modules and rules for IPv4 and IPv6 {{cmd|<nowiki># rc-service iptables start
# rc-service ip6tables start </nowiki>}}

=== Configuration files ===

Your [[Alpine Wall]] configuration files go in {{Path|/etc/awall/optional}}. From version 0.2.12 and later, Awall will look for ''Policy'' files in both the former and {{Path|/usr/share/awall/optional}}
Each such file is called a ''Policy''. 

You may have multiple ''Policy'' files. It is useful to have separate files for eg. HTTP, FTP, etc.
The ''Policy(s)'' can be enabled or disabled by using the command: {{cmd|<nowiki># awall [enable|disable]</nowiki>}}

An AWall ''Policy'' can contain definitions of:
* variables ''(like {{Path|/etc/shorewall/params}})''
* zones ''(like {{Path|/etc/shorewall/zones}})''
* interfaces ''(like {{Path|/etc/shorewall/interfaces}})''
* policies ''(like {{Path|/etc/shorewall/policy}})''
* filters and NAT rules ''(like {{Path|/etc/shorewall/rules}})''
* services ''(like {{Path|/usr/share/shorewall/macro.HTTP}})''

== Basic home firewall configuration ==

The examples below show how to configure a basic home firewall using AWall. Note that AWall Policy files differ substantially from Shorewall's policy files in syntax and layout.

=== Shorewall configuration ===

Let's suppose you have the following Shorewall configuration files in {{Path|/etc/shorewall/}}, which you want to convert to a [[#AWall configuration|configuration for AWall]]. {{cat|/etc/shorewall/zones|inet ipv4
loc ipv4}}

{{cat|/etc/shorewall/interfaces|inet eth0
loc eth1}}

{{cat|/etc/shorewall/policy|fw all ACCEPT
loc inet ACCEPT
all all DROP}}

{{cat|/etc/shorewall/masq|eth0 0.0.0.0/0}}

=== AWall configuration ===

The equivalent AWall configuration that does the same thing as the above [[#Shorewall configuration|Shorewall example]] is given below.

Create a new file called {{Path|/etc/awall/optional/home-policy.json}} and add the following content {{Cat|/etc/awall/optional/home-policy.json|<nowiki>
{
"description": "Home firewall",

"zone": {
"inet": { "iface": "eth0" },
"loc": { "iface": "eth1" }
},

"policy": [
{ "in": "_fw", "action": "accept" },
{ "in": "loc", "out": "inet", "action": "accept" }
],

"snat": [
{ "out": "inet" }
]
}</nowiki>}}

The above configuration will:
* Create a description of your ''Policy''
* Define ''zones''
* Define ''policy''
* Define ''snat'' ''(to masqurade the outgoing traffic)''

'''snat''' means "source NAT". It does not mean "static NAT".

{{Tip| AWall has a built-in zone named "_fw" which is the "firewall itself". This corresponds to the Shorewall "fw" zone.}}

=== Activating/Applying a Policy ===

After saving the ''Policy'' you can run the following commands to activate your firewall settings.
To listing available 'Policy(s)' {{cmd|# awall list}}
To enable the 'Policy' created in the previous section:{{cmd|# awall enable home-policy}}
To generate firewall configuration from the 'Policy' file and enable it i.e start the firewall: {{Cmd|# awall activate}}

If you have multiple policies, after enabling or disabling them, you need to always run {{Codeline|'''awall activate'''}} in order to update the iptables rules.

== Advanced configuration ==

Assuming you have your {{Path|/etc/awall/optional/home-policy.json}} with your "Basic home firewall" settings, you could choose to modify that file to test the below examples. You could also create new files in {{Path|/etc/awall/optional/}} for testing some of the below examples.

AWall already has a "service" definition list for several services like HTTP, FTP, SNMP, etc. '' in the file {{Path|/usr/share/awall/mandatory/services.json}})''

{{Note|If you are adding the sample content given in this section to an already existing policy file, then make sure you add "," signs where they are needed!}}

=== Logging ===

AWall will ''(since v0.2.7)'' automatically log dropped packets.

You could add the following row to the "policy" section in your ''Policy'' file in order to see the dropped packets.
<pre>{ "in": "inet", "out": "loc", "action": "drop" }</pre>

=== Port forwarding ===

Let's suppose you have a local web server (192.168.1.10) that you want to make accessible from the "inet". 
With Shorewall you would have a rule like this in your {{Cat|/etc/shorewall/rules|<nowiki>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCEPORT(S) ORIGINALDEST
DNAT inet loc:192.168.1.10 tcp 80</nowiki>}}

Lets configure our AWall ''Policy'' file likewise by adding the following content.
<pre>
"variable": {
"APACHE": "192.168.1.10",
"STATIC_IP": "1.2.3.4"
},

"filter": [
{ "in": "inet",
"dest": "$STATIC_IP",
"service": "http",
"action": "accept",
"dnat": "$APACHE"
}
]
</pre>
As you can see in the above example, we create a
* "variable" section where we specify some IP-addresses
* "filter" section where we do the actual port-forwarding (using the variables we just created and using some preexisting "services" definitions)

If you need to forward to a different port (e.g. 8080) you can do:

<pre>
"dnat": [
{"in": "inet", "dest": "$STATIC_IP", "to-addr": "$APACHE", "service": "http", "to-port": 8080 }
]
</pre>

=== Create your own service definitions ===

{{Note| You can not override a "service" definition that comes from {{Path|/usr/share/awall/mandatory/services.json}}}}

You can add your own service definitions into your ''Policy'' files:
<pre>
"service": {
"openvpn": { "proto": "udp", "port": 1194 }
}
</pre>

=== Inherit services or variables ===

You can import a ''Policy'' into other ''Policy'' files for inheriting services or variables definitions:
<pre>
"import": "myfirewall"
</pre>

=== Customize policy loading order ===

By default policies are loaded on alphabetical order. The load order can be changed with the keywords "before" and "after":
<pre>
"before": "myfirewall"
"after": "someotherpolicy"
</pre>

== Troubleshooting ==

If you end up in some kind of trouble, you might find some commands useful when debugging:
{{cmd|awall # (With no parameters) Shows some basic help about awall application
awall dump # Dump definitions like zones and variables
iptables -L -n # Show what's in <code>iptables</code>}}

== See also ==

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
* [[Zero-To-Awall]]
* [https://www.cyberciti.biz/faq/how-to-set-up-a-firewall-with-awall-on-alpine-linux/ How To Set Up a Firewall with Awall on Alpine Linux]

[[Category:Firewall]]

Zero-To-Awall

2026-01-24T16:45:40Z

Prabuanand: fixed heading level and introduction page, added wikilink

This [https://git.alpinelinux.org/awall/about/ Alpine Wall] howto is aimed at users with no or little experience with iptables and other firewall framework. [[How-To Alpine Wall]] page is aimed at users familiar with shorewall.

== Base policies ==

Be aware that all configuration files are stored as JSON files. JSON is not a human friendly standard, for instance it does not support comments so you will have to move them outside of the json structure.

Beginners should use a decent text editor with JSON highlight support which will make your life easier. Recent versions of Alpine Wall support using yaml instead of json but this is out of scope of this howto.

Creating zones depends on the function of your firewall. Is it installed on a endpoint (server) or will it act as a router and filter/forward.

For this howto we assume you are going to setup a router and use NAT to forward services (ports) to different hosts on your network.

For each interface on router we will setup a zone and assign it a zone name. We do this by creating the following file: /etc/awall/private/base.json
<pre>
{
"description": "Base zones and policies",

"zone": {
"WAN": { "iface": "eth0" },
"LAN": { "iface": "eth1" },
"VPN": { "iface": "tun+" }
},

"policy": [
{ "in": "VPN", "action": "accept" },
{ "out": "VPN", "action": "accept" },
{ "in": "LAN", "action": "accept" },
{ "out": "LAN", "action": "accept" },
{ "in": "_fw", "action": "accept" },
{ "in": "_fw", "out": "WAN" , "action": "accept" },
{ "in": "WAN", "action": "drop" }
],

"snat": [ { "out": "WAN" } ],

"clamp-mss": [ { "out": "WAN" } ]

}
</pre>

Lets break this down into sections

=== description ===

The description is here just for reference and will be used by <code>awall list</code>.

=== zone ===

This is where our zones are defined. Zones are defined based on a interface and assigned a name to be used in your policies.
In our example you can see that we have two real interfaces eth0 and eth1 and one or more virtual interfaces tun+ (the plus sign stands for any digit like tun0 tun1 and so on). In case you are installing awall on an endpoint (a server) then you will most probably not have the eth1 interfaces and can leave it out. In our example the tun+ interface is added as it is very commonly used like when using openvpn.

=== policy ===

These are our main policies. It will tell our firewall what to do with when a packet enters or leaves from one of the zones (interfaces).
You will notice a special <code>_fw</code> name which means the internal firewall (the local machine) which means the packet does not leave the firewall via another interface but should be send to one of the local services.
You can see that we by default do not filter any package coming from or going to our VPN zone/interface. You could instead change the default action to drop all packets and create separate policies to allow specific traffic but this is out of the scope of this howto.

=== snat ===

Apply source nat for outgoing packets. This is only needed if your firewall acts as a router and traffic behind the router needs a modified source address (translate from local ip to public ip).

=== clamp-mss ===

https://github.com/alpinelinux/awall#mss-clamping-rules

== Service policies ==

Now that we have the base firewall in place we can start to define specific policies so our services will be reachable from the outside world.\
By default we are blocking all traffic coming in on our WAN interface (action=drop). The first thing we want to open is our SSH port/service. To do this we need to create a new policy inside the "optional" directory.
You could be wondering why the optional name, thats is because mandatory policies are stored in <code>/usr/share/awall/mandatory</code> and not to be touched and our optional policies can be enabled/disabled on the run.

=== SSH service ===

To add our SSH policies we create a new file: /etc/awall/optional/ssh.json
<pre>
{
"description": "Allow rate-limited SSH on WAN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "ssh",
"action": "accept",
"conn-limit": { "count": 3, "interval": 20 }
}
]
}
</pre>

==== description ====

This is similar for any policy

==== Filter ====

This is the actual filter that is currently set to drop the packets arriving or leaving the interface.

===== in =====

The interface the packets arrive on, in this case its the WAN interface.

===== out =====

The interface the packets leave on, in this case its _fw which means it does not leave our firewall/device and is targeted at our local SSH service.

===== service =====

This is the service definition provided by awall or a custom service which we will discuss later on.

===== action =====

The action on the packet, this inverts the default action of drop and accepts the packets.

===== conn-limit =====

This is a special feature of our firewall/iptables to allow only a certain amount of packets in a certain amount of time. For more information please check our awall manual.

=== SSH to another Host ===

edit the following file: /etc/awall/optional/ssh-to-hostname.json

<pre>
{

"description": "Forward SSH to hostname",

"filter": [
{
"in": "WAN",
"service": { "proto": "tcp", "port": 22001 },
"action": "accept",
"conn-limit": { "count": 3, "interval": 20 }
}
],

"dnat": [
{
"in": "WAN",
"dest": "$SERVER",
"service": { "proto": "tcp", "port": 22001 },
"to-port": "22"
}
]
}
</pre>

Lets discuss the differences between this policy and the previous SSH policy.

==== Filter ====

===== service =====

Because port 22 is already in use by our own firewall, we need to listen on a different port. In this example we listen on port 22001.
And because we are not using the default port 22 we need to define our own service specification.

==== dnat ====

Also known as destination NAT.

===== dest =====

The destination the packet will be forwarded to. In this case we are using a variable named $HOSTNAME. Anywhere in your policies you can define your own variables and use them.
In our case we have used a file in /etc/awall/private/aliases.json more on this topic later on.

===== to-port =====

This is the destination target port number. The packet will be forwarded from 22001 to 22 on the $hostname

=== OpenVPN Service ===

This is the most generic config available. It does nothing more then opening port(s) defined for our openvpn service in {{path|/etc/awall/private/custom-services.json}}

<pre>
{

"description": "Allow local OpenVPN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "openvpn",
"action": "accept"
}
]
}

</pre>

=== Allow ping on WAN ===

Allow rate-limited ping on WAN. Which has the same kind of flow limit as our previous SSH policy.

<pre>
{

"description": "Allow rate-limited ping on WAN",

"filter": [
{
"in": "WAN",
"out": "_fw",
"service": "ping",
"action": "accept",
"flow-limit": { "count": 10, "interval": 6 }
}
]
}
</pre>

== Using aliases and custom services ==

=== Aliases ===

To make life easier when your firewall rules increase, it can be nice to map specific hosts to names.
Awall supports something called [https://github.com/alpinelinux/awall#variable-expansion variable expansion] which is a mapping between a value and a variable.
When you have many devices behind your firewall/router, your policies can be harder to read. Also when one of your devices IP address change you will have to update all of your policies.
With awalls variables you can assign the ip address of a device to a variable name. Edit the following file: <code>/etc/awall/private/aliases.json</code>
<pre>
{
"description": "Hostname aliases",

"variable": {
"PRINTER": "192.168.1.1",
"SERVER": "192.168.1.2"
}

}
</pre>

Look in the example above where $SERVER is used to forward port 22001 to port 22.

NOTE: You are not limited to assigning only IP addresses to variables. You can use it however you like. More information can be found in the awall manual.

=== Custom services ===

Awall includes a predefined list of [https://raw.githubusercontent.com/alpinelinux/awall/master/mandatory/services.json services]. If the service you try to define in your policy does not exist in awalls services list you can define services yourself.

Create the file: {{path|/etc/awall/private/custom-services.json}}

<pre>
{
"service": {

"mqtt": [
{ "proto": "udp", "port": 1883 },
{ "proto": "tcp", "port": 1883 }
],

"openvpn": [
{ "proto": "udp", "port": 1194 },
{ "proto": "tcp", "port": 1194 }
]

}
}
</pre>

NOTE: although you are free to name your policy files however you want, you cannot name this file <code>services.json</code> because this policy name is already in use by the included services.json of awall.

== Using our policies ==

You should now have two directories in your awall config directory named optional and private with multiple json files. The biggest difference between these two directories is the ability to enable and disable policies located in the optional directory. When you enable a policy by using <code>awall enable policy-name</code> awall will generate a symlink in your awall config directory and will automatically load them when you activate the firewall. To be able to also use the files in the private directory we will need to include them in one of our optional policies. You can name the file however you like as long it doesn't conflict with existing policies names (including the ones in private directory and awall's system policies). Example names would be hostname.json main.json firewall.json. For this example we will use main.json.

Create the file: <code>/etc/awall/optional/main.json</code>
<pre>
{
"description": "Main firewall",

"import": [ "base", "aliases", "custom-services" ]

}
</pre>

Contents of your awall directory:
<pre>
awall
│
├── optional
│ ├── main.json
│ ├── openvpn.json
│ ├── ssh-to-hostname.json
│ └── ssh.json
└── private
 ├── aliases.json
 ├── base.json
 └── custom-services.json
</pre>

=== Enabling optional policies ===

Lets enable our created policies. First we list them by running <code>awall list</code> which would show something like:
<pre>
openvpn disabled Allow local OpenVPN
main disabled Main firewall
ping disabled Allow rate-limited ping on WAN
ssh disabled Allow rate-limited SSH on WAN
ssh-to-hostname disabled Forward SSH to hostname
</pre>

Each of these needs to be enabled:
<pre>
awall enable openvpn
awall enable main
awall enable ping
awall enable ssh
awall enable ssh-to-hostname
</pre>

The contents of your awall directory should now look like:
<pre>
awall/
├── main.json -> ./optional/main.json
├── openvpn.json -> ./optional/openvpn.json
├── optional
│ ├── main.json
│ ├── openvpn.json
│ ├── ping.json
│ ├── ssh-to-hostname.json
│ └── ssh.json
├── ping.json -> ./optional/ping.json
├── private
│ ├── aliases.json
│ ├── base.json
│ └── custom-services.json
├── ssh-to-hostname.json -> ./optional/ssh-to-hostname.json
└── ssh.json -> ./optional/ssh.json

2 directories, 13 files
</pre>

=== Testing policies ===

<code>awall translate --verify</code>

if everything goes well the output should be null.

=== Activating the firewall ===

Now that all our policies are verified for proper json we can activate it.

<code>awall activate</code>

This will load the firewall rules and show you a message to confirm. If by accident you made a mistake and lock yourself out you just have to wait for awall to disable itself again.

== Finishing up ==

=== Activating firewall rules at boot ===

When awall has been properly activated it will generate a file with all iptables rules which iptables will read when its is started via openrc.
Make sure you have added iptables to an openrc runlevel. If using snat, also enable ipset for the masquerade set.

<code>rc-update add iptables</code>

<code>rc-update add ipset</code>

=== Allow IPv4 forwarding ===

To allow iptables to forward packets from one zone to the other we need to enable this at the iptables level.

==== On the fly ====

To enable it on the fly:
<code>sysctl -w net.ipv4.ip_forward=1</code>

==== Enable within iptables tools (at boot) ====

Add the following to:
<code>/etc/conf.d/iptables</code>
<pre>
# Enable/disable IPv4 forwarding with the rules
IPFORWARD="yes"
</pre>

== See also ==
* [[How-To Alpine Wall]]
* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
[[Category:Firewall]]

Alpine Wall User's Guide

2026-01-24T16:35:38Z

Prabuanand: added redirect link

#REDIRECT [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]

How-To Alpine Wall

2026-01-24T16:21:16Z

Prabuanand: additional changes by rewording sentence based on email from W. Michael Petullo <mike@flyn.org>

This guide shows how to configure a firewall using Alpine Wall (awall), a Linux firewall configuration tool, providing various benefits over plain iptables. [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide] is the official source for details about the syntax.

The purpose of this page is to illustrate Alpine Wall (AWall) by example. This page explains AWall from the viewpoint of {{pkg|Shorewall}}, a firewall configuration tool used in many applications. This comparison is meant to help readers who are familiar with Shorewall learn AWall. You should follow the AWall configuration examples. Use the Shorewall examples as contextual references, or ignore them, if unfamiliar with Shorewall.

== Installation ==

Install the {{pkg|awall}} package by running the following command:{{cmd|# apk add iptables awall}}

Note that awall requires {{pkg|iptables}} but works with both backends [[nftables]] and legacy [[iptables]]. It does not interact with nftables directly.

== Configuration ==

The easier method for performing initial steps for running awall: {{cmd|# awall activate}}
The above command has special handling for the first run, when firewall is not yet enabled in the kernel. It performs the below manual steps and also updates the default runlevel and files in {{Path|/etc/conf.d}}

Use the below commands for performing initial setup manually.
* To update /etc/iptables: {{cmd|# awall translate}}
* To start the [[OpenRC]] services for iptables and load modules and rules for IPv4 and IPv6 {{cmd|<nowiki># rc-service iptables start
# rc-service ip6tables start </nowiki>}}

=== Configuration files ===

Your [[Alpine Wall]] configuration files go in {{Path|/etc/awall/optional}}. From version 0.2.12 and later, Awall will look for ''Policy'' files in both the former and {{Path|/usr/share/awall/optional}}
Each such file is called a ''Policy''. 

You may have multiple ''Policy'' files. It is useful to have separate files for eg. HTTP, FTP, etc.
The ''Policy(s)'' can be enabled or disabled by using the command: {{cmd|<nowiki># awall [enable|disable]</nowiki>}}

An AWall ''Policy'' can contain definitions of:
* variables ''(like {{Path|/etc/shorewall/params}})''
* zones ''(like {{Path|/etc/shorewall/zones}})''
* interfaces ''(like {{Path|/etc/shorewall/interfaces}})''
* policies ''(like {{Path|/etc/shorewall/policy}})''
* filters and NAT rules ''(like {{Path|/etc/shorewall/rules}})''
* services ''(like {{Path|/usr/share/shorewall/macro.HTTP}})''

== Basic home firewall configuration ==

The examples below show how to configure a basic home firewall using AWall. Note that AWall Policy files differ substantially from Shorewall's policy files in syntax and layout.

=== Shorewall configuration ===

Let's suppose you have the following Shorewall configuration files in {{Path|/etc/shorewall/}}, which you want to convert to a [[#AWall configuration|configuration for AWall]]. {{cat|/etc/shorewall/zones|inet ipv4
loc ipv4}}

{{cat|/etc/shorewall/interfaces|inet eth0
loc eth1}}

{{cat|/etc/shorewall/policy|fw all ACCEPT
loc inet ACCEPT
all all DROP}}

{{cat|/etc/shorewall/masq|eth0 0.0.0.0/0}}

=== AWall configuration ===

The equivalent AWall configuration that does the same thing as the above [[#Shorewall configuration|Shorewall example]] is given below.

Create a new file called {{Path|/etc/awall/optional/home-policy.json}} and add the following content {{Cat|/etc/awall/optional/home-policy.json|<nowiki>
{
"description": "Home firewall",

"zone": {
"inet": { "iface": "eth0" },
"loc": { "iface": "eth1" }
},

"policy": [
{ "in": "_fw", "action": "accept" },
{ "in": "loc", "out": "inet", "action": "accept" }
],

"snat": [
{ "out": "inet" }
]
}</nowiki>}}

The above configuration will:
* Create a description of your ''Policy''
* Define ''zones''
* Define ''policy''
* Define ''snat'' ''(to masqurade the outgoing traffic)''

'''snat''' means "source NAT". It does not mean "static NAT".

{{Tip| AWall has a built-in zone named "_fw" which is the "firewall itself". This corresponds to the Shorewall "fw" zone.}}

=== Activating/Applying a Policy ===

After saving the ''Policy'' you can run the following commands to activate your firewall settings.
To listing available 'Policy(s)' {{cmd|# awall list}}
To enable the 'Policy' created in the previous section:{{cmd|# awall enable home-policy}}
To generate firewall configuration from the 'Policy' file and enable it i.e start the firewall: {{Cmd|# awall activate}}

If you have multiple policies, after enabling or disabling them, you need to always run {{Codeline|'''awall activate'''}} in order to update the iptables rules.

== Advanced configuration ==

Assuming you have your {{Path|/etc/awall/optional/home-policy.json}} with your "Basic home firewall" settings, you could choose to modify that file to test the below examples. You could also create new files in {{Path|/etc/awall/optional/}} for testing some of the below examples.

AWall already has a "service" definition list for several services like HTTP, FTP, SNMP, etc. '' in the file {{Path|/usr/share/awall/mandatory/services.json}})''

{{Note|If you are adding the sample content given in this section to an already existing policy file, then make sure you add "," signs where they are needed!}}

=== Logging ===

AWall will ''(since v0.2.7)'' automatically log dropped packets.

You could add the following row to the "policy" section in your ''Policy'' file in order to see the dropped packets.
<pre>{ "in": "inet", "out": "loc", "action": "drop" }</pre>

=== Port forwarding ===

Let's suppose you have a local web server (192.168.1.10) that you want to make accessible from the "inet". 
With Shorewall you would have a rule like this in your {{Cat|/etc/shorewall/rules|<nowiki>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCEPORT(S) ORIGINALDEST
DNAT inet loc:192.168.1.10 tcp 80</nowiki>}}

Lets configure our AWall ''Policy'' file likewise by adding the following content.
<pre>
"variable": {
"APACHE": "192.168.1.10",
"STATIC_IP": "1.2.3.4"
},

"filter": [
{ "in": "inet",
"dest": "$STATIC_IP",
"service": "http",
"action": "accept",
"dnat": "$APACHE"
}
]
</pre>
As you can see in the above example, we create a
* "variable" section where we specify some IP-addresses
* "filter" section where we do the actual port-forwarding (using the variables we just created and using some preexisting "services" definitions)

If you need to forward to a different port (e.g. 8080) you can do:

<pre>
"dnat": [
{"in": "inet", "dest": "$STATIC_IP", "to-addr": "$APACHE", "service": "http", "to-port": 8080 }
]
</pre>

=== Create your own service definitions ===

{{Note| You can not override a "service" definition that comes from {{Path|/usr/share/awall/mandatory/services.json}}}}

You can add your own service definitions into your ''Policy'' files:
<pre>
"service": {
"openvpn": { "proto": "udp", "port": 1194 }
}
</pre>

=== Inherit services or variables ===

You can import a ''Policy'' into other ''Policy'' files for inheriting services or variables definitions:
<pre>
"import": "myfirewall"
</pre>

=== Customize policy loading order ===

By default policies are loaded on alphabetical order. The load order can be changed with the keywords "before" and "after":
<pre>
"before": "myfirewall"
"after": "someotherpolicy"
</pre>

== Troubleshooting ==

If you end up in some kind of trouble, you might find some commands useful when debugging:
{{cmd|awall # (With no parameters) Shows some basic help about awall application
awall dump # Dump definitions like zones and variables
iptables -L -n # Show what's in <code>iptables</code>}}

== See also ==

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
* [[Zero-To-Awall]]
* [https://www.cyberciti.biz/faq/how-to-set-up-a-firewall-with-awall-on-alpine-linux/ How To Set Up a Firewall with Awall on Alpine Linux]

[[Category:Firewall]]

How-To Alpine Wall

2026-01-24T06:35:17Z

Prabuanand: updated instructions based on https://lists.alpinelinux.org/~alpine/devel/%3CaVhxrpww1wvEmBWB%40imp.flyn.org%3E#%3C7f95fffb-67ed-2ea8-95e0-e4794363bed9@alpinelinux.org%3E

[https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide] is the official source for details about the syntax. The purpose of this page is to illustrate Alpine Wall (AWall) by example. This page explains AWall from the viewpoint of a Shorewall user.

== Installation ==

Install the {{pkg|awall}} package by running the following command:{{cmd|# apk add iptables awall}}

Note that awall requires {{pkg|iptables}} but works with both backends [[nftables]] and legacy [[iptables]]. It does not interact with nftables directly.

== Configuration ==

The easier method for performing initial steps for running awall: {{cmd|# awall activate}}
The above command has special handling for the first run, when firewall is not yet enabled in the kernel. It performs the below manual steps and also updates the default runlevel and files in {{Path|/etc/conf.d}}

Use the below commands for performing initial setup manually.
* To update /etc/iptables: {{cmd|# awall translate}}
* To start the [[OpenRC]] services for iptables and load modules and rules for IPv4 and IPv6 {{cmd|<nowiki># rc-service iptables start
# rc-service ip6tables start </nowiki>}}

=== Configuration files ===

Your [[Alpine Wall]] configuration files go in {{Path|/etc/awall/optional}}. From version 0.2.12 and later, Awall will look for ''Policy'' files in both the former and {{Path|/usr/share/awall/optional}}
Each such file is called a ''Policy''. 

You may have multiple ''Policy'' files. It is useful to have separate files for eg. HTTP, FTP, etc.
The ''Policy(s)'' can be enabled or disabled by using the command: {{cmd|<nowiki># awall [enable|disable]</nowiki>}}

An AWall ''Policy'' can contain definitions of:
* variables ''(like {{Path|/etc/shorewall/params}})''
* zones ''(like {{Path|/etc/shorewall/zones}})''
* interfaces ''(like {{Path|/etc/shorewall/interfaces}})''
* policies ''(like {{Path|/etc/shorewall/policy}})''
* filters and NAT rules ''(like {{Path|/etc/shorewall/rules}})''
* services ''(like {{Path|/usr/share/shorewall/macro.HTTP}})''

== Basic home firewall ==

The below example shows the "Basic home firewall" configuration for both Shorewall and AWall. Based on below example, it can be clearly seen that AWall ''Policy'' files are not equivalent to Shorewall's {{Path|/etc/shorewall/policy}} files.

=== Shorewall configuration ===

Let's suppose you have the following Shorewall configuration: {{cat|/etc/shorewall/zones|inet ipv4
loc ipv4}}

{{cat|/etc/shorewall/interfaces|inet eth0
loc eth1}}

{{cat|/etc/shorewall/policy|fw all ACCEPT
loc inet ACCEPT
all all DROP}}

{{cat|/etc/shorewall/masq|eth0 0.0.0.0/0}}

=== AWall configuration ===

The equivalent AWall configuration that does the same thing as the above Shorewall example is given below.

Create a new file called {{Path|/etc/awall/optional/home-policy.json}} and add the following content {{Cat|/etc/awall/optional/home-policy.json|<nowiki>
{
"description": "Home firewall",

"zone": {
"inet": { "iface": "eth0" },
"loc": { "iface": "eth1" }
},

"policy": [
{ "in": "_fw", "action": "accept" },
{ "in": "loc", "out": "inet", "action": "accept" }
],

"snat": [
{ "out": "inet" }
]
}</nowiki>
}}
The above configuration will:
* Create a description of your ''Policy''
* Define ''zones''
* Define ''policy''
* Define ''snat'' ''(to masqurade the outgoing traffic)''

'''snat''' means "source NAT". It does not mean "static NAT".

{{Tip| AWall has a built-in zone named "_fw" which is the "firewall itself". This corresponds to the Shorewall "fw" zone.}}

=== Activating/Applying a Policy ===

After saving the ''Policy'' you can run the following commands to activate your firewall settings:
{{cmd|awall list # Listing available 'Policy(s)' (This step is optional)
awall enable test-policy # Enables the 'Policy'
awall activate # Genereates firewall configuration from the 'Policy' files and enables it (starts the firewall)}}

If you have multiple policies, after enabling or disabling them, you need to always run ''awall activate'' in order to update the iptables rules.

== Advanced configuration ==

Assuming you have your {{Path|/etc/awall/optional/home-policy.json}} with your "Basic home firewall" settings, you could choose to modify that file to test the below examples.

{{Tip|You could also create new files in {{Path|/etc/awall/optional/}} for testing some of the below examples}}

=== Logging ===

AWall will ''(since v0.2.7)'' automatically log dropped packets.

You could add the following row to the "policy" section in your ''Policy'' file in order to see the dropped packets.
<pre>{ "in": "inet", "out": "loc", "action": "drop" }</pre>

{{Note|If you are adding the above content to an already existing file, then make sure you add "," signs where they are needed!}}

=== Port forwarding ===

Let's suppose you have a local web server (192.168.1.10) that you want to make accessible from the "inet". 
With Shorewall you would have a rule like this in your {{Path|/etc/shorewall/rules}}:
<pre>
#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL
# PORT(S) PORT(S) DEST
DNAT inet loc:192.168.1.10 tcp 80
</pre>

Lets configure our AWall ''Policy'' file likewise by adding the following content.
<pre>
"variable": {
"APACHE": "192.168.1.10",
"STATIC_IP": "1.2.3.4"
},

"filter": [
{ "in": "inet",
"dest": "$STATIC_IP",
"service": "http",
"action": "accept",
"dnat": "$APACHE"
}
]
</pre>
As you can see in the above example, we create a
* "variable" section where we specify some IP-addresses
* "filter" section where we do the actual port-forwarding (using the variables we just created and using some preexisting "services" definitions)
{{Note|If you are adding the above content to a already existing file, then make sure you add "," signs where they are needed!}}
{{Tip|AWall already has a "service" definition list for several services like HTTP, FTP, SNMP, etc. ''(see {{Path|/usr/share/awall/mandatory/services.json}})''}}

If you need to forward to a different port (e.g. 8080) you can do:

<pre>
"dnat": [
{"in": "inet", "dest": "$STATIC_IP", "to-addr": "$APACHE", "service": "http", "to-port": 8080 }
]
</pre>

=== Create your own service definitions ===

{{Note| You can not override a "service" definition that comes from {{Path|/usr/share/awall/mandatory/services.json}}}}

You can add your own service definitions into your ''Policy'' files:
<pre>
"service": {
"openvpn": { "proto": "udp", "port": 1194 }
}
</pre>
{{Note|If you are adding the above content to a already existing file, then make sure you add "," signs where they are needed!}}

=== Inherit services or variables ===

You can import a ''Policy'' into other ''Policy'' files for inheriting services or variables definitions:
<pre>
"import": "myfirewall"
</pre>

=== Customize policy loading order ===

By default policies are loaded on alphabetical order. The load order can be changed with the keywords "before" and "after":
<pre>
"before": "myfirewall"
"after": "someotherpolicy"
</pre>

== Troubleshooting ==

If you end up in some kind of trouble, you might find some commands useful when debugging:
{{cmd|awall # (With no parameters) Shows some basic help about awall application
awall dump # Dump definitions like zones and variables
iptables -L -n # Show what's in <code>iptables</code>}}

== See also ==
* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
* [[Zero-To-Awall]]
* [https://www.cyberciti.biz/faq/how-to-set-up-a-firewall-with-awall-on-alpine-linux/ How To Set Up a Firewall with Awall on Alpine Linux]

[[Category:Firewall]]

How-To Alpine Wall

2026-01-24T06:04:44Z

Prabuanand: removed wrong instructions based on email from Kaarle Ritvanen in alpine-devel mailing list 8 days ago

[https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide] is the official source for details about the syntax. The purpose of this page is to illustrate Alpine Wall (AWall) by example. This page explains AWall from the viewpoint of a Shorewall user.

== Configuration files ==

Your [[Alpine Wall]] configuration files go in {{Path|/etc/awall/optional}}. From version 0.2.12 and later, Awall will look for ''Policy'' files in both the former and {{Path|/usr/share/awall/optional}}
Each such file is called a ''Policy''. 

You may have multiple ''Policy'' files. It is useful to have separate files for eg. HTTP, FTP, etc.
The ''Policy(s)'' can be enabled or disabled by using the command: {{cmd|<nowiki># awall [enable|disable]</nowiki>}}

An AWall ''Policy'' can contain definitions of:
* variables ''(like {{Path|/etc/shorewall/params}})''
* zones ''(like {{Path|/etc/shorewall/zones}})''
* interfaces ''(like {{Path|/etc/shorewall/interfaces}})''
* policies ''(like {{Path|/etc/shorewall/policy}})''
* filters and NAT rules ''(like {{Path|/etc/shorewall/rules}})''
* services ''(like {{Path|/usr/share/shorewall/macro.HTTP}})''

== Basic home firewall ==

The below example shows the "Basic home firewall" configuration for both Shorewall and AWall. Based on below example, it can be clearly seen that AWall ''Policy'' files are not equivalent to Shorewall's {{Path|/etc/shorewall/policy}} files.

=== Shorewall configuration ===

Let's suppose you have the following Shorewall configuration: {{cat|/etc/shorewall/zones|inet ipv4
loc ipv4}}

{{cat|/etc/shorewall/interfaces|inet eth0
loc eth1}}

{{cat|/etc/shorewall/policy|fw all ACCEPT
loc inet ACCEPT
all all DROP}}

{{cat|/etc/shorewall/masq|eth0 0.0.0.0/0}}

=== AWall configuration ===

The equivalent AWall configuration that does the same thing as the above Shorewall example is given below.

Create a new file called {{Path|/etc/awall/optional/home-policy.json}} and add the following content {{Cat|/etc/awall/optional/home-policy.json|<nowiki>
{
"description": "Home firewall",

"zone": {
"inet": { "iface": "eth0" },
"loc": { "iface": "eth1" }
},

"policy": [
{ "in": "_fw", "action": "accept" },
{ "in": "loc", "out": "inet", "action": "accept" }
],

"snat": [
{ "out": "inet" }
]
}</nowiki>
}}
The above configuration will:
* Create a description of your ''Policy''
* Define ''zones''
* Define ''policy''
* Define ''snat'' ''(to masqurade the outgoing traffic)''

'''snat''' means "source NAT". It does not mean "static NAT".

{{Tip| AWall has a built-in zone named "_fw" which is the "firewall itself". This corresponds to the Shorewall "fw" zone.}}

=== Activating/Applying a Policy ===

After saving the ''Policy'' you can run the following commands to activate your firewall settings:
{{cmd|awall list # Listing available 'Policy(s)' (This step is optional)
awall enable test-policy # Enables the 'Policy'
awall activate # Genereates firewall configuration from the 'Policy' files and enables it (starts the firewall)}}

If you have multiple policies, after enabling or disabling them, you need to always run ''awall activate'' in order to update the iptables rules.

== Advanced configuration ==

Assuming you have your {{Path|/etc/awall/optional/home-policy.json}} with your "Basic home firewall" settings, you could choose to modify that file to test the below examples.

{{Tip|You could also create new files in {{Path|/etc/awall/optional/}} for testing some of the below examples}}

=== Logging ===

AWall will ''(since v0.2.7)'' automatically log dropped packets.

You could add the following row to the "policy" section in your ''Policy'' file in order to see the dropped packets.
<pre>{ "in": "inet", "out": "loc", "action": "drop" }</pre>

{{Note|If you are adding the above content to an already existing file, then make sure you add "," signs where they are needed!}}

=== Port forwarding ===

Let's suppose you have a local web server (192.168.1.10) that you want to make accessible from the "inet". 
With Shorewall you would have a rule like this in your {{Path|/etc/shorewall/rules}}:
<pre>
#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL
# PORT(S) PORT(S) DEST
DNAT inet loc:192.168.1.10 tcp 80
</pre>

Lets configure our AWall ''Policy'' file likewise by adding the following content.
<pre>
"variable": {
"APACHE": "192.168.1.10",
"STATIC_IP": "1.2.3.4"
},

"filter": [
{ "in": "inet",
"dest": "$STATIC_IP",
"service": "http",
"action": "accept",
"dnat": "$APACHE"
}
]
</pre>
As you can see in the above example, we create a
* "variable" section where we specify some IP-addresses
* "filter" section where we do the actual port-forwarding (using the variables we just created and using some preexisting "services" definitions)
{{Note|If you are adding the above content to a already existing file, then make sure you add "," signs where they are needed!}}
{{Tip|AWall already has a "service" definition list for several services like HTTP, FTP, SNMP, etc. ''(see {{Path|/usr/share/awall/mandatory/services.json}})''}}

If you need to forward to a different port (e.g. 8080) you can do:

<pre>
"dnat": [
{"in": "inet", "dest": "$STATIC_IP", "to-addr": "$APACHE", "service": "http", "to-port": 8080 }
]
</pre>

=== Create your own service definitions ===

{{Note| You can not override a "service" definition that comes from {{Path|/usr/share/awall/mandatory/services.json}}}}

You can add your own service definitions into your ''Policy'' files:
<pre>
"service": {
"openvpn": { "proto": "udp", "port": 1194 }
}
</pre>
{{Note|If you are adding the above content to a already existing file, then make sure you add "," signs where they are needed!}}

=== Inherit services or variables ===

You can import a ''Policy'' into other ''Policy'' files for inheriting services or variables definitions:
<pre>
"import": "myfirewall"
</pre>

=== Customize policy loading order ===

By default policies are loaded on alphabetical order. The load order can be changed with the keywords "before" and "after":
<pre>
"before": "myfirewall"
"after": "someotherpolicy"
</pre>

== Troubleshooting ==

If you end up in some kind of trouble, you might find some commands useful when debugging:
{{cmd|awall # (With no parameters) Shows some basic help about awall application
awall dump # Dump definitions like zones and variables
iptables -L -n # Show what's in <code>iptables</code>}}

== See also ==
* [https://git.alpinelinux.org/awall/about/ Alpine Wall User Guide]
* [[Zero-To-Awall]]
* [https://www.cyberciti.biz/faq/how-to-set-up-a-firewall-with-awall-on-alpine-linux/ How To Set Up a Firewall with Awall on Alpine Linux]

[[Category:Firewall]]

Talk:Zram

2026-01-12T12:42:51Z

Prabuanand: replied Macmpi

Advanced setups may also add these parameters to /etc/sysctl.conf as follows
Would be nice to add more explanations and references (like [https://wiki.archlinux.org/title/Zram#Optimizing_swap_on_zram this]?).
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 12:50, 11 Jan 2025 (UTC)
:Hi [[User:Macmpi|Macmpi]], In the past, just like this page, i moved or re-arranged existing content on the wiki from various pages. Most of these content move/changes were made by me after testing the instructions, but i was not aware of their source. I fully agree that quoting sources is quite important in technical documentation like wiki. In future, i'll add sources. Thanks for the note. -[[User:Prabuanand|Prabuanand]] ([[User talk:Prabuanand|talk]]) 12:42, 12 January 2026 (UTC)

User:Prabuanand

2026-01-11T18:02:48Z

Prabuanand: fixed url typo

http://git.sr.ht/~prabuanand/dotfiles

==Stuff to watch==
[[Special:Patroller|Unpatrolled edits]]
Most recent unpatrolled new pages (ideally there should be none): {{Special:NewPages/limit=50,hidepatrolled}}

[[Special:BrokenRedirects|List of broken redirects]] (there should be none)

[[Special:DoubleRedirects|List of double redirects]] (there should be none)

[[Special:ListDuplicatedFiles|List of duplicate files]] (there should be none)

[https://wiki.alpinelinux.org/w/index.php?target=irc%3A%2F%2F*&title=Special%3ALinkSearch All irc:// hyperlinks]. (there should be none)

[[Special:TrackingCategories|Pages that mediawiki has marked as broken in some way]] (there should be none)

[[Special:RecentChanges|250 most recent wiki edits]]

==To-do==

[[Special:WhatLinksHere/Template:Dead_link|Pages which contain dead links]]

[[Special:WhatLinksHere/Template:Obsolete|Obsolete pages]] (Need to go through and RfD some of these)

[[Special:WhatLinksHere/Template:Insecure_url|Pages which contain links to unencrypted content]] (Some sites stubbornly refuse to join the current century)

[[Special:WhatLinksHere/Template:Delete|RfDs]] (I don't have access to deal with these)

[[Special:WantedPages|List of non-existing pages that are linked to]]

[https://wiki.alpinelinux.org/w/index.php?target=http%3A%2F%2F*&title=Special%3ALinkSearch All http:// hyperlinks]. All of these need to be checked to see if they can be rewritten to https://

[https://wiki.alpinelinux.org/w/index.php?target=ftp%3A%2F%2F*&title=Special%3ALinkSearch All ftp:// hyperlinks]. All of these need to be check to see if an sftp:// or https:// version is available.

[https://wiki.alpinelinux.org/w/index.php?target=svn%3A%2F%2F*&title=Special%3ALinkSearch All svn:// hyperlinks]. Old Alpine SVN links have gotta go!

==Tools==

[[Special:LinkSearch|External link seach]]

[[Special:AllPages/Template:|List of all templates]]

[[Special:ExpandTemplates|Template wikimarkup expansion tool]]

[[Special:Redirect|Redirect by file, user, page, revision, or log ID]]

[[Special:AbuseFilter|Description of automatic abuse filtering]] (because I always forget, and it would be nice to be able to explain to new wiki users why exactly their posts are getting denied)

[[Special:Random|Go to a completely random page.]] This is both fun and useful!

==Logs/Stats==

[[Special:BlockList]]

[[Special:AbuseLog]]

[[Special:Statistics]]