blockdiag

What it is and what it does

blockdiag is a text-to-diagram generator that converts a simple dot-like specification language into block-diagram images. You write a plain-text file describing nodes and transitions, then run blockdiag to produce PNG output (or optionally PDF with additional dependencies). It's designed for system administrators and developers who need to document workflows, system architectures, or process flows without using a graphical editor.

The package depends on Pillow for image rendering, funcparserlib for parsing the specification syntax, webcolors for color handling, and setuptools. It supports UTF-8 multilingual labels on nodes. The main limitation is that the project is no longer actively maintained—the last release was in December 2021, so bugs and compatibility issues with newer Python versions or dependencies may not be addressed.

Use it for:

• Document system administration workflows or process flows as text-based diagrams that can be version-controlled.
• Generate architecture diagrams for technical documentation without requiring a GUI tool.
• Create flowcharts for application logic or user journeys in a reproducible, text-driven format.
• Embed diagram generation into build pipelines or documentation systems that consume text specifications.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

blockdiag generates block-diagram images from a dot-like text specification format, supporting multilingual node labels and multiple output formats.

Yes, if you need a lightweight, text-driven block-diagram generator and can tolerate an abandoned codebase. The package is stable and has no known vulnerabilities, but expect no bug fixes or feature updates. It works reliably for basic diagrams on supported Python versions. Avoid it if you require active maintenance, support for newer Python versions, or ongoing feature development.

Install

blockdiag on PyPI

pip install blockdiag

uv add blockdiag

poetry add blockdiag

Installing blockdiag

Before you install

Low install friction with a pure-Python wheel distribution. However, the package is abandoned—last release was 2021-12-06, with no active maintenance despite the repository remaining unarchived.

License in practice

Apache License 2.0 is permissive, allowing commercial and private use with minimal restrictions. You may use, modify, and distribute blockdiag freely as long as you include a copy of the license.

Quickstart

pip install blockdiag

Create a file `diagram.diag`:
  diagram admin {
    top_page -> config -> config_edit -> top_page;
  }

Then run: blockdiag diagram.diag
Output: diagram.png

Requires Python 3.7 or later; Pillow 3.0 or later is a runtime dependency.

Verify before relying

• Whether the package works reliably with Python versions beyond 3.9 (classifiers list only up to 3.9).
• Current state of optional dependencies (reportlab, wand/imagemagick) and whether PDF export still functions.
• Whether the dot-like syntax is fully documented and stable for new users.

Package facts

Evidence: blockdiag-3.0.0-py3-none-any.whl

Keywords: diagram, generator

Tags

More Software Development packages