diskimage-builder

3.41.0 verified Mon Apr 27 auth: no python

diskimage-builder is the golden disk image builder used by OpenStack for creating disk images. It provides a set of tools and elements to build customizable operating system images. Current version is 3.41.0, with a stable release cadence. Requires Python >=3.8.

pip install diskimage-builder

Common errors

error disk-image-create: command not found ↓

cause diskimage-builder's executables are not in PATH, or package not installed.

fix

Install via 'pip install diskimage-builder' and ensure Python Scripts directory is in PATH (e.g., ~/.local/bin).

error ImportError: No module named yaml ↓

cause Missing PyYAML dependency, often due to environment isolation.

fix

Run 'pip install pyyaml' or 'pip install diskimage-builder[pyyaml]'.

error Permission denied: /tmp/dib_build_* ↓

cause Running without root privileges; diskimage-builder needs to mount loop devices.

fix

Prepend 'sudo' or run as root user. Alternatively, use --no-tmpfs and ensure user has loop device access.

Warnings

breaking Python 2 support removed in version 2.x. Elements that rely on Python 2 will fail. ↓

fix Ensure all elements are Python 3 compatible, or pin to version 1.x if legacy support needed.

gotcha disk-image-create requires root privileges (sudo) for mounting images, which can lead to permission issues if forgotten. ↓

fix Run commands with sudo or configure user namespace support in your environment.

deprecated The 'element_dependencies' function is deprecated in favor of explicit element list definitions. ↓

fix Switch to defining dependencies in element.yaml files or using DIB_REQUIRE_ELEMENTS.

gotcha Elements may fail silently if dependencies are missing, producing corrupted images. ↓

fix Always test images in a VM and check DIB_DEBUG_TRACE=1 for verbosity.

Imports

diskimage_builder
```
import diskimage_builder
```
The package is imported as diskimage_builder (with underscore), not diskimage-builder.
elements
```
from diskimage_builder import elements
```
Elements are modules inside the package, typically accessed via diskimage_builder.element_dependencies or as a script.

Quickstart

Build a basic Ubuntu disk image using disk-image-create script. Set ELEMENTS_PATH to include custom elements if needed.

#!/bin/bash
export ELEMENTS_PATH=/path/to/elements
disk-image-create -a amd64 -o my-image ubuntu