apk(8)

📦
version 3.0.9 · 8 versions
, in arch rolling

💅 apk(8) — Alpine Package Keeper 🌸

okay bestie, buckle up, because this is the page for apk itself — yes, the manual page for the whole apk(8) situation, the main character of Alpine package management. Everything else gets its own page, so think of this one as the group chat admin 💖

✨ SYNOPSIS ✨

apk [<global options>...] command [<options>...] [<arguments>...]

🦋 DESCRIPTION 🦋

apk manages the packages installed on your system. The whole set of top-level constraints on system packages is called the world (go read apk-world(5) for that whole lore, iykyk).

apk has a bunch of sub-commands for querying and manipulating the world and package repositories. Like, a lot of sub-commands. We'll get to them 💀

Every single apk command that modifies the database gets logged to /var/log/apk.log. So yes, it remembers things, no cap.

By default apk is non-interactive. If you wanna change that default to be interactive, peep the FILES section or just use --interactive.

Heads up: only global options should be given before the command. For backwards compatibility apk makes a best-effort attempt to parse applet-specific options before the command, but that's deprecated and subject to being removed. So don't get attached to it, bestie 😭

👑 COMMANDS 👑

Every command has its own detailed manual page, so if you're obsessed with one in particular, go read its own page for the full tea.

🎀 PACKAGE INSTALLATION AND REMOVAL

  • apk-add(8) — add or modify constraints in world and commit the changes ✨
  • apk-del(8) — remove constraints from world and commit the changes 🗑️

🧚 SYSTEM MAINTENANCE

🔥 QUERYING PACKAGE INFORMATION

  • apk-query(8) — query information about packages by various criteria
  • apk-list(8) — list packages matching a pattern or other criteria
  • apk-dot(8) — render dependencies as graphviz graphs (graph girlies rise 🫶)
  • apk-policy(8) — show repository policy for packages
  • apk-search(8) — search for packages by name or description
  • apk-info(8) — give detailed information about packages or repositories

💜 REPOSITORY AND PACKAGE MAINTENANCE

🌈 MISCELLANEOUS

🌸 OPTION SYNTAX 🌸

okay this part is important so listen up 👀

The BOOL argument for options is either 'yes' or 'no'. The AUTO argument for options is 'yes', 'no' or 'auto'. What the default value actually is depends on the specific option, so it's giving "it varies."

For options that take an AUTO or BOOL argument, the argument must be given in the --option=argument format. That means the --option argument format is not supported. Sorry babe 💅

On top of that, these little aliases exist:

  • --option equals --option=yes
  • --no-option equals --option=no

⭐ GLOBAL OPTIONS ⭐

These are available for all commands, no matter which one you pick. Slay.

  • --allow-untrusted — install packages with an untrusted signature, or with no signature at all 🙈
  • --arch ARCH — temporarily override architectures. The first --arch you give becomes the primary architecture, and it's used to work out the paths where package indexes get downloaded from. Any additional architectures you list specify compatible packages that are considered for installation.

When you use it together with --root, the architecture also gets saved.

  • --cache[=BOOL] — when disabled, prevents using any local cache paths.
  • --cache-dir CACHEDIR — temporarily override the cache directory. CACHEDIR is treated relative to the ROOT.
  • --cache-max-age AGE — max AGE (in minutes) for an index in the cache before it gets refreshed. 0 means always refresh.
  • --cache-packages[=BOOL] — store a copy of packages in the cache at installation time. Enabled automatically if the /etc/apk/cache symlink exists.
  • --cache-predownload[=BOOL] — download the needed packages to the cache before starting to commit a transaction. Requires the cache to be configured to actually be functional. Implies --cache-packages.
  • --check-certificate[=BOOL] — when disabled, omits validation of the HTTPS server certificate.
  • --force, -f — enable selected --force-* options (deprecated ⚠️).
  • --force-binary-stdout — continue even if binary data is gonna get printed to the terminal.
  • --force-broken-world — DANGEROUS: delete world constraints until a solution without conflicts is found. This does not allow installing packages with unsatisfiable dependencies, and it's mainly intended for initramfs boot — it's implied by --initramfs-diskless-boot. The primary purpose is to let run-from-tmpfs systems boot if the media was upgraded and some packages are no longer available in the new release.

APK will try to determine which world constraints are causing the conflicting dependencies, and start disabling world constraints in that order until a satisfiable set of constraints is left. Using this switch on a hard disk installation will likely result in unexpected removal of some packages. If you're uncertain, use it with --interactive or --simulate first. fr fr, be careful 😭

  • --force-missing-repositories — continue even if some of the repository indexes aren't available.
  • --force-no-chroot — disable chroot for scripts. This can be used for rootfs creation when chroot isn't available. Scripts running outside a chroot environment may modify and damage the host system. 💀
  • --force-non-repository — continue even if packages may be lost on reboot. This can happen when running in run-from-tmpfs mode and installing a non-repository package.
  • --force-old-apk — continue even if packages use unsupported features.
  • --force-overwrite — overwrite files in other packages.
  • --force-refresh — do not use cached files (local or from proxy).
  • --help, -h — print the list of all commands with descriptions.
  • --interactive[=AUTO] — determine if questions can be asked before performing certain operations. In auto mode, interactive mode is enabled if running on a tty. Defaults to no, or auto if /etc/apk/interactive exists.
  • --keys-dir KEYSDIR — override the default system trusted keys directories. If specified, only this directory is processed. The KEYSDIR is treated relative to ROOT.
  • --legacy-info[=BOOL] — print output from the info applet in legacy format or the new query format. Defaults to no currently, but the default is subject to change to yes in a future release.
  • --logfile[=BOOL] — if turned off, disables the writing of the log file.
  • --network[=BOOL] — if turned off, does not use the network. The packages from network repositories in the cache are used.
  • --preserve-env[=BOOL] — allow passing the user environment down to scripts (excluding variables starting with APK_, which are reserved).
  • --pretty-print[=AUTO] — determine if output should be stylized to be human readable. Defaults to auto, which resolves to yes if running on a tty. 💖
  • --preupgrade-depends DEPS — add or modify preupgrade dependencies. The preupgrade dependencies are used to match installed packages that are eligible for preupgrade. E.g. 'apk-tools' will always preupgrade the 'apk-tools' package, but 'baselayout<2' would preupgrade the 'baselayout' only if the installed version of baselayout is less than 2 and an upgrade is available. See also apk-upgrade(8).
  • --print-arch — print the default arch and exit.
  • --progress[=AUTO] — enable or disable the progress bar. Defaults to auto, which resolves to yes if running on a tty.
  • --progress-fd FD — write progress to the specified file descriptor.
  • --purge[=BOOL] — purge modified configuration and cached packages. Enables deletion of modified configuration files on package removal. On cache clean action, this enables deletion of unneeded cached packages (uninstalled packages on tmpfs installations, or all packages on disk installations).
  • --quiet, -q — print less information.
  • --repositories-file REPOFILE — override system repositories, see apk-repositories(5). Specifying this option overrides the normal repositories file and the repositories.d directory processing. The given REPOFILE is relative to the startup directory since apk 2.12.0_rc2.
  • --repository, -X REPO — specify an additional package repository. apk-repositories(5) specified commands are not parsed (use --repository-config for that). Additionally, relative paths are accepted and interpreted relative to the startup directory.
  • --repository-config REPOCONFIG — specify additional package repository configuration. The REPOCONFIG is parsed exactly the same way as if it was read from an apk-repositories(5) specified .list file.
  • --root, -p ROOT — manage the file system at ROOT.
  • --root-tmpfs[=AUTO] — specify if the ROOT is a temporary filesystem. Defaults to auto, which determines the filesystem type automatically.

This affects:

  • reading and creation of the 'installed' index in the cache
  • purging of packages in cache
  • safety checks to not install non-repository packages
  • --sync[=AUTO] — determine if filesystem caches should be committed to disk. Defaults to auto, which resolves to yes if --root is not specified, the database is not in usermode, and it's running on the root pid namespace (so, not containerized).
  • --timeout TIME — timeout network connections if no progress is made in TIME seconds. The default is 60 seconds. ⏰
  • --update-cache, -U — alias for '--cache-max-age 0'.
  • --uvol-manager UVOL — specify the OpenWRT uvol volume manager executable location.
  • --verbose, -v — print more information (can be specified twice 👀).
  • --version, -V — print program version and exit.
  • --wait TIME — wait for TIME seconds to get an exclusive repository lock before failing.

💾 COMMIT OPTIONS

Okay bestie, these are the options that work on every single command that commits the database. Like, if it's writing to the DB, these apply. Periodt.

  • --clean-protected[=BOOL] — turn this off and apk will not create those .apk-new files in your configuration directories. So basically it stops dropping new config files next to your old ones. Handle with care, mwah 💋
  • --commit-hooks[=BOOL] — disabled means it skips the pre/post hook scripts entirely (but NOT the other scripts, so don't get it twisted 🙈).
  • --initramfs-diskless-boot — this one's for initramfs when it's out there recreating the root tmpfs. It enables selected force options to minimize failure, and it disables commit hooks, among other features. Very niche, very demure ✨
  • --overlay-from-stdin — reads a list of overlay files from stdin. Normally this is used only during initramfs when booting a run-from-tmpfs installation. iykyk 🫶
  • --scripts[=BOOL] — disabled means no scripts execute at all. Super useful for extracting a system image for a different architecture on an alternative ROOT. Lowkey a lifesaver for cross-arch stuff 🧚
  • --simulate[=BOOL], -s — simulates the operation you asked for without actually changing anything 🎀. The database gets opened in read only mode, and auto-updating of indexes is disabled. Pro tip from the manpage itself: you may want to run apk update before running a simulation so you know it's working with up-to-date repository indexes. No cap, do that 💅

📦 GENERATION OPTIONS

These are for all the commands that generate APKv3 files. Making files? This is your section, bestie.

  • --compression, -c ALGORITHM[:LEVEL]` — compresses the file with the given ALGORITHM and LEVEL. The supported algorithms are honestly a whole vibe:
    • none
    • deflate (level 1-9)
    • zstd (level 1-22)
  • --sign-key KEYFILE — signs the file with a private key in the specified KEYFILE. Secure the bag 🔐

🌱 ENVIRONMENT

The variables apk reads, aka the vibes it picks up from your shell:

  • APK_CONFIG — overrides the default config file name. See /etc/apk/config 👀
  • LANG — used to determine if UTF-8 is supported, and sets the default progress character accordingly 🌈
  • SOURCE_DATE_EPOCH — see apk-index(8) ✨
  • TERM — used to determine if the terminal is dumb or not. On dumb terminals the progress bar is not enabled by default. Sad but fair 😭

🔌 Variables to configure built-in libfetch

Networking bestie section, let's go:

  • FETCH_BIND_ADDRESS — a local IP address that libfetch will bind all the sockets it creates to. Can be useful for source routing. Fancy 🎀
  • NETRC — specifies the .netrc file to read for authentication secrets. If you don't set it, it defaults to $HOME/.netrc 🫶
  • HTTP_AUTH
  • HTTP_REFERER
  • HTTP_USER_AGENT — these three let you specify a custom HTTP-level Authorization, Referer or User-Agent header. Customize away 💅
  • HTTP_PROXY, http_proxy
  • HTTPS_PROXY, https_proxy — if set, these should contain the proxy URL for http and https connections respectively. Yes both cases, they're not out here being picky ✨
  • HTTP_PROXY_AUTH — specifies a HTTP Proxy-Authorization header. Used only if the connection is established through a configured HTTP proxy. Conditional queen 👑
  • NO_PROXY, no_proxy — comma-separated list of domain extensions or CIDR notation IP addresses that should never use a proxy. Important caveat incoming: this is used explicitly to test the URL hostname portion only. So specifying an IP address or CIDR block will not match a DNS name that resolves to that IP address. Read that twice, bestie 📖
  • SSL_CLIENT_CERT_FILE
  • SSL_CLIENT_KEY_FILE — override the default SSL client certificate and corresponding private key filename 🔐
  • SSL_NO_VERIFY_HOSTNAME — if set to anything at all, disables the server certificate name verification. Danger vibes, use with intention 💀

🧚 Environment for the scripts APK executes

Normally apk executes scripts with a sanitized, minimal environment containing only PATH. See also --preserve-env if you wanna pass along extra environment variables 🌸

Before executing a script, apk sets the working directory as ROOT and performs a chroot — unless --force-no-chroot is specified. Either way, the script's working directory should be treated as the system root. Don't forget that, fr fr 🫶

The environment variables that APK itself defines are:

  • APK_PACKAGE — the package name (package scripts only) 📦
  • APK_SCRIPT — set to one of the package or commit script types. Use this to figure out the script hook type if you need to. And listen: the filename ($0) is not reliable, because apk prefers to execute package scripts from a memfd file. Iconic but chaotic 💀

📁 FILES

⚙️ Configuration files

  • /etc/apk/config
  • /lib/apk/config

These are the default global options. Only the first file existing in the above list is read and parsed. The one in /lib is meant for distribution default options, which can then be overridden by the user with the file in /etc. See also the APK_CONFIG environment variable 🎀

A configuration file contains one long option per line. For example:

no-cache
timeout 120
  • /etc/apk/interactive — if this file exists, it defaults --interactive to auto. Cute little presence flag ✨

🗂️ Configuration files (relative to --root)

  • /etc/apk/arch — the CPU architecture for this database. See apk-package(5) section on package metadata field arch for the list 💅
  • /etc/apk/cache — this is expected to be a symlink to the directory that apk will use as the package cache. See also /var/cache/apk below, plus apk-cache(5) and apk-cache(8) 🫶
  • /etc/apk/commit_hooks.d/*
  • /lib/apk/commit_hooks.d/*

Hook scripts, and they're dramatic: they run before anything has been written to the filesystem, and again after all the changes have been committed. The script gets the stage name as an argument (pre-commit or post-commit). And if the script returns failure during the pre-commit stage, the commit is aborted — no takebacks 😤

See also the ENVIRONMENT section for the environment variables.

If --no-scripts or --no-commit-hooks is specified, these hook scripts are not executed. Periodt.

  • /etc/apk/keys
  • /lib/apk/keys

Directories for trusted signing keys 🔑. They're enumerated in the order above, and once a given filename is seen, any file of the same name in subsequent directories is ignored. First come, first served 💅

  • /etc/apk/protected_paths.d/*.list — configuration files that specify how to treat changes to specified directory or file masks. The file format is further documented in apk-protected_paths(5) 🎀
  • /etc/apk/repositories
  • /etc/apk/repositories.d/*.list
  • /lib/apk/repositories.d/*.list

Configuration files that specify repositories 📚. These directories are enumerated in the order above, and once a given filename is seen, any file of the same name in subsequent directories is ignored. See apk-repositories(5) for details 🌸

  • /etc/apk/world — top level requirements and constraints on what should be installed. See apk-world(5) for details 👑

🌐 Configuration files for built-in libfetch

  • /etc/apk/ca.pem — the CA certificate store bundle for verifying server certificates. If it's not present, the default system CA store is used instead 🎀
  • /etc/apk/crl.pem — the CRL store to check the server certificates against 🔐
  • /etc/apk/cert.key — client certificate private key 🗝️
  • /etc/apk/cert.pem — client certificate to use for authentication ✨

🖥️ System files and directories

  • /lib/apk/db/lock — a lock file, there to allow only one concurrent write transaction on the system. One at a time, bestie 🙅‍♀️
  • /lib/apk/db/installed — the database of installed packages and their contents 📦
  • /lib/apk/db/scripts.tar
  • /lib/apk/db/scripts.tar.gz

The collection of all package scripts from currently installed packages 🗃️

  • /lib/apk/db/triggers — the list of triggers rules for currently installed packages ⚡
  • /lib/apk/db-uvol — a database symlink or a directory with a similar structure as /lib/apk/db/, but used for package content when managed using the OpenWRT uvol volume manager 🌀
  • /lib/apk/exec — the temporary directory for extraction and execution of package scripts and triggers 🧚
  • /var/log/apk.log — the log file for changes done to the system 📝
  • /var/cache/apk — if the /etc/apk/cache symlink does not exist or is dangling, this directory is used as a cache for repository indices 🗂️

☕ NOTES

This apk has coffee making abilities.

Yes, that's literally what it says. Not me making things up, bestie — it's in the actual manual page. Iconic. Legendary. Never been done before. 👑☕✨

🌸 And that's a wrap on apk(8), bestie! This page is © the Alpine Linux project, dated 2026-11-02 — go forth and slay your packages 💅🎀🦋

📦 where this page comes from