Skip to main content
Installing packages in Minimus images is a great way to customize them on the fly for your exact requirements.

​
Prerequisites

When installing packages, make sure to use Minimus containers that meet both conditions:
  1. Can run apk commands - Minimus dev images fit the bill
  2. Run as root - usually this is not the default in Minimus images so you’ll need to switch to a root user
Keep in mind that Minimus production images are usually not a good fit because they are distroless. This means they don’t include the necessary packages. You can always check the image’s SBOM to be sure.

​
Install packages during runtime (inside a running container)

  1. Run a Minimus docker container as root and make sure the container includes apk. For example, you can run the Bash image with the latest-dev tag: 
    docker run -it -u root reg.mini.dev/bash:latest-dev
  2. Add packages as usual. For example, you can add git: 
    apk add --no-cache git
    Since Minimus images point /etc/apk/repositories at packages.mini.dev/os by default, there’s no need to explicitly point at the MinimOS package repository. This is an example of redundant code that isn’t recommended: 
    apk add --no-cache --repository=https://packages.mini.dev/os git

​
In a Dockerfile

You can install MinimOS packages directly within your Dockerfile during the image build. Since the MinimOS package repository is open to all, there is no need to pass credentials unless you require them. Below is an example of the code to be added to your Dockerfile:
Dockerfile code snippet that installs MinimOS public packages
...
USER root

# Update APK and install packages
RUN apk update && \
    apk add --no-cache \
        <pkg1> \
        <pkg2>
...
For example, you might add the following code to your Dockerfile to install curl and jq:
filename
FROM reg.mini.dev/python:3.13
RUN apk add --no-cache curl jq

​
Python tutorial example (multi-stage build)

The following example builds on the multi-stage pattern from the Minimus Python guide. We will follow the steps in the original guide, replacing only the Dockerfile and build command. The Dockerfile uses a latest-dev builder for package installation and Python dependencies and switches to the minimal Python image at runtime.
Dockerfile with apk add steps
# === Build Stage ===
FROM reg.mini.dev/python:latest-dev AS builder

WORKDIR /app

# Install system packages from the MinimOS package repository
USER root
RUN apk update && \
    apk add --no-cache \
        build-base \
        libffi-dev

RUN python -m venv /app/venv
ENV PATH="/app/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# === Runtime Stage ===
FROM reg.mini.dev/python:latest

WORKDIR /app

COPY main.py .
COPY --from=builder /app/venv /app/venv
ENV PATH="/app/venv/bin:$PATH"

ENTRYPOINT ["python", "main.py"]
Note that all apk commands stay in the latest-dev build stage and are executed as USER root to avoid Unable to lock database: Permission denied. The runtime image reg.mini.dev/python:latest is distroless and does not include /bin/sh, so RUN apk ... is not supported there. Run the build command as usual: 
docker compose build
Last modified on June 16, 2026