apk add: Usage, Options & Common CI Errors
apk add installs packages on Alpine Linux, the tiny base image favored for CI.
apk is Alpine's package manager and the reason Alpine images are so small. The flag you will use most in CI is --no-cache, and the error you will hit most is "unsatisfiable constraints".
What it does
apk add installs packages and their dependencies from Alpine repositories. It is fast and the indexes are tiny. Build-time-only dependencies are commonly grouped into a "virtual" package so they can be removed in one step after the build.
Common usage
apk add --no-cache curl git ca-certificates
apk add --no-cache --virtual .build-deps gcc musl-dev make
# ... build ...
apk del .build-deps # remove the build deps
apk add --no-cache nodejs=20.15.1-r0 # pin an exact versionCommon errors in CI
"ERROR: unable to select packages: X (no such package)" means the package name differs from Debian (e.g. it is musl-dev, not libc6-dev) or the repo is not enabled. "unsatisfiable constraints" appears when a pinned version no longer exists (Alpine prunes old versions aggressively) or two deps conflict - drop the pin or run apk update. glibc-only binaries fail at runtime on musl with "Error loading shared library ... No such file or directory". Use --no-cache so no index is left in the layer.
Options
| Flag | What it does |
|---|---|
| --no-cache | Do not cache the index (no apk update needed) |
| --virtual <name> | Group packages so apk del removes them together |
| --no-progress | Suppress the progress bar in logs |
| -t / --virtual | Alias for creating a virtual package |
| del <name> | Remove a package or virtual group |