# How to Add Custom apt Packages or pip Packages to LabNow AI Base Docker Images

> Easily add custom apt or pip packages to LabNow AI Docker images. Learn how to edit .apt and .pip files to customize your AI environment and rebuild your image.

- Repository: [LabNow.ai/lab-foundation](https://github.com/labnow-ai/lab-foundation)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Add custom apt packages by editing `.apt` list files under `docker_atom/work/` or `docker_core/work/`, add pip packages by editing `.pip` files in `docker_core/work/`, then rebuild the image using the standard Docker build commands.**

The LabNow AI foundation repository (`labnow-ai/lab-foundation`) provides a modular Docker build system that lets you extend base Ubuntu 22.04 images with custom system-level dependencies and Python libraries. Understanding how to add custom apt packages or pip packages to LabNow AI base Docker images allows you to tailor the environment for specific scientific computing, data science, or machine learning workflows without modifying the underlying Dockerfile logic.

## Understanding the LabNow AI Docker Build Architecture

The build system organizes images into three logical layers: `docker_atom` (minimal utilities), `docker_base` (core Ubuntu system), and `docker_core` (Python environment with conda). The helper functions `install_apt` and `install_pip` defined in [`docker_atom/work/script-utils.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-utils.sh) drive the installation process by reading plain-text list files.

During the build, the `Dockerfile` in `docker_base/` sources these utilities and calls `install_apt /opt/utils/install_list_base.apt` to install system packages. Similarly, `docker_core/Dockerfile` invokes `install_pip` against various `.pip` list files to populate the conda-managed Python environment at `/opt/conda`.

## Adding Custom apt Packages to LabNow AI Images

### Locate the Correct .apt List File

Identify which layer needs the package. For system utilities required by all downstream images, edit `docker_atom/work/install_list_base.apt`. For flavor-specific dependencies (e.g., CUDA tools, database clients), locate the relevant `.apt` file under `docker_core/work/` or specific sub-folders like `docker_db_postgres/rootfs/opt/utils/`.

### Edit the Package List

Open the target file and append your package names. The format accepts one package per line with optional comments after a `%` symbol:

```text
ffmpeg libavcodec-dev libavformat-dev    % multimedia processing libraries
libgdal-dev                              % geospatial data abstraction

```

Do not include version pinning in the list file; the `install_apt` function runs `apt-get install --no-install-recommends -y` for each entry.

### Rebuild the Docker Image

Navigate to the appropriate directory and trigger the build:

```bash
cd docker_base
docker build -t labnow/base:custom .

```

The build automatically sources [`script-utils.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/script-utils.sh) and executes `install_apt` against your modified list.

### Verify the Installation

Run a container from the new image and check for the package:

```bash
docker run --rm labnow/base:custom dpkg -l | grep ffmpeg

```

The output should list the installed version of `ffmpeg` and its dependencies.

## Adding Custom pip Packages to LabNow AI Images

### Choose the Right .pip List File

The `docker_core/work/` directory contains multiple `.pip` files organized by flavor:

- `install_list_PY_base.pip` – Core Python libraries used across all images
- `install_list_PY_datascience.pip` – Data science specific packages
- `install_list_PY_nlp.pip` – Natural language processing libraries

Select the file that corresponds to the image variant you are building.

### Append Python Packages

Add your package names following the same comment syntax:

```text
sentence-transformers                % state-of-the-art sentence embeddings
polars                               % fast DataFrame library

```

The `install_pip` function reads this file and executes `pip install --no-cache-dir -U --pre` for each line, installing packages into the conda environment at `/opt/conda`.

### Build and Verify

Build the core image:

```bash
cd docker_core
docker build -t labnow/core:custom .

```

Test the installation by importing the module:

```bash
docker run --rm labnow/core:custom python -c "import sentence_transformers; print(sentence_transformers.__version__)"

```

## Key Files and Helper Functions Reference

| File Path | Purpose |
|-----------|---------|
| [`docker_atom/work/script-utils.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-utils.sh) | Defines `install_apt` and `install_pip` helper functions used across all builds. |
| `docker_atom/work/install_list_base.apt` | Base system packages installed in every image. |
| `docker_base/Dockerfile` | Core image definition that sources utilities and calls `install_apt`. |
| `docker_core/work/install_list_PY_base.pip` | Core Python packages for the conda environment. |
| `docker_core/work/install_list_PY_datascience.pip` | Data science flavor Python packages. |
| `docker_core/Dockerfile` | Builds the Python environment and invokes `install_pip`. |

## Summary

- **Edit `.apt` files** under `docker_atom/work/` or `docker_core/work/` to add system packages, then rebuild the base image.
- **Edit `.pip` files** under `docker_core/work/` to add Python libraries, then rebuild the core image.
- **Use the helper functions** `install_apt` and `install_pip` defined in [`docker_atom/work/script-utils.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-utils.sh) to ensure consistent installation behavior.
- **Verify installations** by running containers and checking package versions before pushing to production registries.

## Frequently Asked Questions

### Can I add packages without rebuilding the entire image?

No. The LabNow AI build system processes package lists at build time through the `install_apt` and `install_pip` functions. To include new dependencies, you must modify the relevant `.apt` or `.pip` file and run `docker build` again. For temporary testing, you can manually install packages inside a running container using `apt-get` or `pip`, but these changes will not persist in the image.

### What is the difference between docker_atom and docker_core?

`docker_atom` contains the minimal utility layer including [`script-utils.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/script-utils.sh) and `install_list_base.apt`, providing the foundational `install_apt` helper used by all downstream images. `docker_core` builds upon this to create the Python environment using conda, managing `.pip` package lists for specific flavors like data science or NLP. Think of `docker_atom` as the system foundation and `docker_core` as the Python runtime layer.

### How do I specify package versions in the list files?

The standard list files support simple package names without version pinning, relying on the latest available version in the Ubuntu or PyPI repositories. If you require specific versions, you can append the version constraint directly in the list file using standard pip or apt syntax, such as `numpy==1.24.0` for pip or `postgresql-client-14=14.9-0ubuntu0.22.04.1` for apt. The `install_pip` function passes these strings directly to `pip install`, while `install_apt` passes them to `apt-get install`.

### Where are the install_apt and install_pip functions defined?

Both helper functions are defined in [`docker_atom/work/script-utils.sh`](https://github.com/labnow-ai/lab-foundation/blob/main/docker_atom/work/script-utils.sh). The `install_apt` function updates the apt cache and installs packages without recommended extras using `apt-get install --no-install-recommends -y`. The `install_pip` function installs Python packages into the conda environment at `/opt/conda` using `pip install --no-cache-dir -U --pre`. These functions are sourced early in the Docker build process to ensure consistent package management across all LabNow AI image variants.