{"id":9555,"library":"blockdiag","title":"blockdiag","description":"blockdiag generates block-diagram images from simple text definitions. It is part of the diag suite of tools for various diagrams and is currently at version 3.0.0. Its release cadence is feature-driven, providing updates for new Python versions and enhancements.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/blockdiag/blockdiag","tags":["diagram","chart","visualization","text-to-image","image generation"],"install":[{"cmd":"pip install blockdiag","lang":"bash","label":"Install core library"}],"dependencies":[{"reason":"Required for generating PNG and other raster image formats.","package":"Pillow","optional":false}],"imports":[{"note":"The parser is located in the `parser` submodule, not directly under the main package.","wrong":"from blockdiag.blockdiag import parse_string","symbol":"parse_string","correct":"from blockdiag.parser import parse_string"},{"note":"The main image generation utility is found in the `command.blockdiag` submodule, typically for programmatic use.","wrong":"from blockdiag import generate_image","symbol":"generate_image","correct":"from blockdiag.command.blockdiag import generate_image"}],"quickstart":{"code":"from blockdiag.parser import parse_string\nfrom blockdiag.command.blockdiag import generate_image\nfrom io import BytesIO\nimport os\n\ndiagram_text = \"\"\"\ndiagram {\n  A -> B -> C;\n  B -> D;\n}\n\"\"\"\n\ntry:\n    # Parse the diagram definition\n    tree = parse_string(diagram_text)\n\n    # Generate the image to a BytesIO object\n    output_image_stream = BytesIO()\n    generate_image(tree, format='png', output_filename=output_image_stream)\n\n    # You can now save output_image_stream.getvalue() to a file\n    output_filename = os.environ.get('BLOCKDIAG_OUTPUT_FILE', 'example_diagram.png')\n    with open(output_filename, \"wb\") as f:\n        f.write(output_image_stream.getvalue())\n\n    print(f\"Diagram generated to {output_filename}\")\n\nexcept ImportError as e:\n    print(f\"Error: {e}. Make sure blockdiag and Pillow are installed.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically generate a block diagram. It parses a diagram definition string, then uses `generate_image` to create a PNG image into a BytesIO object, which is then saved to a file."},"warnings":[{"fix":"Upgrade your Python environment to 3.7+ and ensure all dependencies are compatible. For older Python 2 projects, stick to blockdiag 2.x.","message":"Blockdiag 3.x removed support for Python 2.x. It now requires Python 3.7 or newer.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always ensure Pillow is installed alongside blockdiag: `pip install blockdiag Pillow`.","message":"The `Pillow` library is a mandatory runtime dependency for generating raster images (e.g., PNG, JPEG). Without it, image generation will fail or only SVG output will be possible.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly specify a font using the `font` argument (programmatic) or `-f` option (CLI) with a path to a universally available font (e.g., DejaVu Sans). On Linux servers, install common font packages (e.g., `fonts-dejavu-core`).","message":"Font rendering can be inconsistent across different operating systems or headless environments. Missing fonts can lead to default fallback fonts or incorrect text display.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the official documentation or quickstart examples for correct import paths, typically `from blockdiag.parser import parse_string` and `from blockdiag.command.blockdiag import generate_image`.","message":"The programmatic API for blockdiag is not always immediately obvious. Many users mistakenly try to import directly from `blockdiag` instead of specific submodules like `blockdiag.parser` or `blockdiag.command.blockdiag`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"The `generate_image` function is located in `blockdiag.command.blockdiag`. Correct imports are `from blockdiag.parser import parse_string` and `from blockdiag.command.blockdiag import generate_image`.","cause":"Incorrect import path for programmatic usage, commonly when trying to guess the location of the `generate_image` function.","error":"ModuleNotFoundError: No module named 'blockdiag.command'"},{"fix":"Ensure `blockdiag` is installed in the active virtual environment (`pip install blockdiag`). If using a global install, make sure the Python user scripts directory (e.g., `~/.local/bin` on Linux) is included in your system's PATH.","cause":"The `blockdiag` command-line tool is not in your system's PATH, or the package was not installed with its entry points.","error":"blockdiag: command not found"},{"fix":"Verify the font file exists and the path is correct and accessible to the process running blockdiag. For headless servers, ensure necessary font packages (e.g., `fonts-dejavu-core` on Debian/Ubuntu) are installed.","cause":"The specified font file (via the `font` argument or `-f` CLI option) could not be found, is inaccessible, or is corrupt.","error":"IOError: Unable to load font '/path/to/font.ttf'"},{"fix":"Install or upgrade Pillow to a compatible version: `pip install Pillow>=6.0.0`. If an old `PIL` (Python Imaging Library) is present, uninstall it first (`pip uninstall PIL`).","cause":"This usually indicates that the `Pillow` library, a core dependency for image output, is either not installed, an incompatible version is present, or there's a conflict with an old `PIL` installation.","error":"AttributeError: 'module' object has no attribute 'Image'"}]}