> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Package Access

> Install Minimus packages directly in Minimus image using a package manager to experiment and test out options

Image Creator is usually the optimal way to add packages to Minimus images, but when you need the extra freedom to test out options and decide which packages you will need, direct package access is available.

Package access allows you to add Minimus packages directly in your Dockerfile or install them in a running container so you can experiment within the Minimus ecosystem.

## Creator vs. package access

[Image Creator](https://images.minimus.io/creator) is the standard choice when working with Minimus because it allows Minimus to handle all of the following for you:

* Package version updates. [See advisories](/remediate/advisories)
* Image updates. [See daily builds](/foundations/daily-updates)
* Vulnerability reports. [See image version card](/foundations/image-version)
* Changelog. [See image card](/foundations/image-card#changelog)
* Builds of all versions. [See versions](/introduction/versions)

When using package access to install packages ad-hoc, you (or someone on your team) will need to manually handle the above tasks. That said, package access is a common choice and is fully supported by Minimus.

## Requesting package access

Package access is not enabled by default, so you'll need to request access to have it enabled for your tenant. Visit the [Tokens page](https://images.minimus.io/manage/tokens) in your Minimus console and select the option to **Request package access**.

<Frame>
  <img src="https://mintcdn.com/gutsy-6162adbc/DdI-xllBqTbrg94d/images/request-package-access.png?fit=max&auto=format&n=DdI-xllBqTbrg94d&q=85&s=bbd2dbac35de912a1a54f206dd62f9ed" alt="Request Package Access" width="1481" height="1229" data-path="images/request-package-access.png" />
</Frame>

Fill out the contact form and our team will follow up with you shortly thereafter.

<Frame>
  <img src="https://mintcdn.com/gutsy-6162adbc/DdI-xllBqTbrg94d/images/request-package-access-contact-form.png?fit=max&auto=format&n=DdI-xllBqTbrg94d&q=85&s=835dbc248653a449688154ffbf647307" alt="Request Package Access Contact Form" width="1551" height="1187" data-path="images/request-package-access-contact-form.png" />
</Frame>

## Authenticate to packages.mini.dev

Learn how to authenticate to the Minimus Package Repository both at runtime and during the Docker build process.

### 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](/basics/user#switch-users-in-the-dockerfile)

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](/foundations/image-card) to be sure.

### During runtime (inside a container)

1. Create a token with **package access scope**. See [tokens](/manage/token)
   <Frame>
     <img src="https://mintcdn.com/gutsy-6162adbc/DdI-xllBqTbrg94d/images/package-access-token.png?fit=max&auto=format&n=DdI-xllBqTbrg94d&q=85&s=38467657debc8da213bea2102b1abce9" alt="Package Access Token" width="1541" height="1110" data-path="images/package-access-token.png" />
   </Frame>
2. 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:
   ```shellscript theme={null}
   docker run -it -u root reg.mini.dev/bash:latest-dev
   ```
3. In the container, authenticate to the Minimus package registry:
   ```shell package access command wrap theme={null}
   export HTTP_AUTH="basic:packages.mini.dev:minimus:mini_dkj***"
   apk update
   ```
   Once authenticated, the session will remain active until the token expires.
4. Add packages as usual. For example, you can add `git`:
   ```text theme={null}
   apk add --no-cache --repository=https://packages.mini.dev/os git
   ```

### In a Dockerfile

You can install packages directly within your Dockerfile by authenticating during the image build. As is standard practice in CI pipelines, this approach uses a build variable like `${REPO_PASS}` to securely handle credentials.

Below is an example of the code to be added to your Dockerfile:

```dockerfile Dockerfile HTTP_AUTH code theme={null}
...
ARG REPO_PASS
ENV HTTP_AUTH="basic:packages.mini.dev:minimus:${REPO_PASS}"

USER root

# Update APK and install packages
RUN apk update && \
    apk add --no-cache \
        <pkg1> \
        <pkg2>
...
```

Build with a Minimus token that has [package access](/manage/token):

<CodeGroup>
  ```shellscript docker build command theme={null}
  docker build --build-arg REPO_PASS={token} -t my-minimus-image:local .
  ```

  ```text example theme={null}
  docker build --build-arg REPO_PASS=mini_dkj*** -t my-minimus-image:local .
  ```
</CodeGroup>

## Python tutorial example (multi-stage build)

The following example builds on the multi-stage pattern from the Minimus [Python guide](/guides/python). 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.

```python Dockerfile with apk add steps theme={null}
# === Build Stage ===
FROM reg.mini.dev/python:latest-dev AS builder

ARG REPO_PASS
ENV HTTP_AUTH="basic:packages.mini.dev:minimus:${REPO_PASS}"

WORKDIR /app

# Install system packages from the Minimus 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.

Add your Minimus token to the build command:

<CodeGroup>
  ```shellscript build command theme={null}
  docker compose build --build-arg REPO_PASS={token}
  ```

  ```shellscript expected output theme={null}
  ...
   => [builder 3/6] RUN apk update &&     apk add --no-cache         build-base         libffi-dev         5.0s
   => CACHED [stage-1 2/4] WORKDIR /app                                                                    0.0s
   => CACHED [stage-1 3/4] COPY main.py .                                                                  0.0s
   ...                                                           0.0s
  [+] build 1/1
   ✔ Image python-apk-flask-app Built   
  ```
</CodeGroup>

## Runtime Troubleshooting

### Auth error

If the remote server returns an error, most likely authentication failed because your token doesn't include package access.

For example: `WARNING: updating and opening https://packages.mini.dev/os: remote server returned error (try 'apk update')`

To fix the issue, edit your token or create a new one with package access scope. See [tokens](https://docs.minimus.io/manage/token)

### Permission denied

If you get an error that permission was denied, most likely you are running as a non-root user and can't modify system files.

For example: `ERROR: Unable to lock database: Permission denied` `ERROR: Failed to open apk database: Permission denied`

To fix the issue, run the container with `-u root` to [override the default user at runtime](/basics/user#override-the-default-user-to-run-as-root).

### APK not found

If you try to run `HTTP_AUTH="basic:packages.mini.dev:token"` and get an error `bash: apk: command not found`, this means you are using a Minimus image that is not able to run apk commands.

To fix the issue, run a [Minimus dev image](/introduction/image-variants) so it includes dev tools.

## Dockerfile Troubleshooting

### Auth error

If you get an error that ends with `exit code: 2`, most likely authentication failed because your token doesn't include package access.

For example: `failed to solve: process "/bin/sh -c apk update &&  apk add --no-cache  <pkg1>  <pkg2>" did not complete successfully: exit code: 2`

To fix the issue, edit your token or create a new one with package access scope. See [tokens](/manage/token)

### Permission denied

If you get an error that ends with `exit code: 99`, most likely you are running as a non-root user and can't modify system files.

For example: `failed to solve: process "/bin/sh -c apk update &&  apk add --no-cache  <pkg1>  <pkg2>" did not complete successfully: exit code: 99`

To fix the issue, edit your Dockerfile to [switch to the root user](https://docs.minimus.io/basics/user#switch-users-in-the-dockerfile) before running the apk commands.