Registry / devops / diskimage-builder

diskimage-builder

library3.42.0pypypi✓ verified 90d ago

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.

devops data

pip install diskimage-builder

package ↗homepage ↗

INSTALL

IMPORT

SIG · DISKIMAGE-BUILDER

diskimage-builder

devopspythonv3.42.0

Install

4.4s avg

Import

—

Disk

52MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.42.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 48.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.4s · import 0.000s · 49MB

52MB installed

● package 52MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

disk-image-builder --version

Debug

Known issues

breakingPython 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.

affects: >=2.0.0

gotchadisk-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.

affects: all

deprecatedThe '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.

affects: >=3.0.0

gotchaElements 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.

affects: all

Errors

Common errors & fixes

disk-image-create: command not found

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).

ImportError: No module named yaml

Missing PyYAML dependency, often due to environment isolation.

fix

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

Permission denied: /tmp/dib_build_*

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.

Upgrade

Version history

3.42.0latest on PyPI · released May 13, 2026

Audit

Dependencies

pyyamlrequiredYAML parsing for element configurations

sixoptionalCompatibility layer for Python 2/3

stevedorerequiredPlugin management for elements

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/diskimage-builder/ ↗

homepagehttps://docs.openstack.org/diskimage-builder/latest/ ↗