{"id":21132,"library":"diskimage-builder","title":"diskimage-builder","description":"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.","status":"active","version":"3.41.0","language":"python","source_language":"en","source_url":"https://github.com/openstack/diskimage-builder","tags":["openstack","disk-image","image-builder","golden-image"],"install":[{"cmd":"pip install diskimage-builder","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"YAML parsing for element configurations","package":"pyyaml","optional":false},{"reason":"Compatibility layer for Python 2/3","package":"six","optional":true},{"reason":"Plugin management for elements","package":"stevedore","optional":false}],"imports":[{"note":"The package is imported as diskimage_builder (with underscore), not diskimage-builder.","wrong":null,"symbol":"diskimage_builder","correct":"import diskimage_builder"},{"note":"Elements are modules inside the package, typically accessed via diskimage_builder.element_dependencies or as a script.","wrong":null,"symbol":"elements","correct":"from diskimage_builder import elements"}],"quickstart":{"code":"#!/bin/bash\nexport ELEMENTS_PATH=/path/to/elements\ndisk-image-create -a amd64 -o my-image ubuntu","lang":"bash","description":"Build a basic Ubuntu disk image using disk-image-create script. Set ELEMENTS_PATH to include custom elements if needed."},"warnings":[{"fix":"Ensure all elements are Python 3 compatible, or pin to version 1.x if legacy support needed.","message":"Python 2 support removed in version 2.x. Elements that rely on Python 2 will fail.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Run commands with sudo or configure user namespace support in your environment.","message":"disk-image-create requires root privileges (sudo) for mounting images, which can lead to permission issues if forgotten.","severity":"gotcha","affected_versions":"all"},{"fix":"Switch to defining dependencies in element.yaml files or using DIB_REQUIRE_ELEMENTS.","message":"The 'element_dependencies' function is deprecated in favor of explicit element list definitions.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Always test images in a VM and check DIB_DEBUG_TRACE=1 for verbosity.","message":"Elements may fail silently if dependencies are missing, producing corrupted images.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Install via 'pip install diskimage-builder' and ensure Python Scripts directory is in PATH (e.g., ~/.local/bin).","cause":"diskimage-builder's executables are not in PATH, or package not installed.","error":"disk-image-create: command not found"},{"fix":"Run 'pip install pyyaml' or 'pip install diskimage-builder[pyyaml]'.","cause":"Missing PyYAML dependency, often due to environment isolation.","error":"ImportError: No module named yaml"},{"fix":"Prepend 'sudo' or run as root user. Alternatively, use --no-tmpfs and ensure user has loop device access.","cause":"Running without root privileges; diskimage-builder needs to mount loop devices.","error":"Permission denied: /tmp/dib_build_*"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}