Diagrams: the wheel ships code and icons, and the library ships nothing you can deploy

It draws the architecture and never touches the cloud

The most useful sentence in this README is a warning. It does not control any actual cloud resources, and it does not generate CloudFormation or Terraform code. It is for drawing cloud system architecture diagrams, and that is the whole job. So a node labelled with an EC2 instance is a rectangle with an icon, not a resource, and a Diagram attribute is a visual, not an API call. This is worth internalising before you build anything on it, because the failure mode is a diagram that looks authoritative in a design review while describing a system nobody has built. The upside is that this constraint is also why the tool is safe: there is no credential to leak, no API to rate limit, and nothing to clean up afterwards. It was born for prototyping a new system architecture design without any design tools, and describing an existing one is the second use.

All three install paths still need a Graphviz binary underneath

Python 3.9 or higher is the stated requirement, and the manifest expresses it as requires-python = "~=3.9", which means anything from 3.9 up to but not including 4.0. Beyond that, the library does not render anything on its own. It uses Graphviz, so the binary has to exist on the machine before the package is useful, which is why the install instructions point at the Graphviz download page first and mention brew install graphviz for macOS users on Homebrew. Then there are three equivalent ways to add the package:

# using pip (pip3)
$ pip install diagrams

# using pipenv
$ pipenv install diagrams

# using poetry
$ poetry add diagrams

The gotcha is CI. A container that installs the Python package and forgets the system package gets an import-time failure at the first render, not at install time, and the error will point at a graphviz executable rather than at your requirements file.

Icons live outside the package directory on purpose

The wheel is built with hatchling and the include list is exactly two entries: the diagrams package and a top-level resources directory. A comment in pyproject.toml explains why the icons are not inside the package. diagrams.Node._load_icon resolves icons relative to the parent of the diagrams package, so resources has to sit next to it at the top level. Practically, that means you cannot vendor a single directory and expect the icons to come with it, and it means the installed tree is the package plus an icon tree and nothing else. The dev environment brings pytest, pylint, rope, isort, black and pre-commit, so the project formats with black and sorts imports with isort, and its linting standard is pylint rather than flake8 or ruff.

The sdist withholds autogen.sh because it cannot run

The sdist include list is longer and just as opinionated: diagrams, resources, tests, scripts/__init__.py, scripts/check_release_version.py and CHANGELOG.md. The stated reason for carrying the test suite and the release-version check is that distribution packagers can verify a build without cloning the repository. The stated reason for excluding the rest of scripts/ and autogen.sh is that those need templates/, website/ and external binaries, and shipping them without their inputs would advertise a script that cannot run. That is a packaging decision you can feel downstream: source distributions for Debian or an internal mirror will not contain the generator, so regenerating resources from templates means going back to the git checkout. One more detail is worth knowing if you run those tests yourself. tests/test_packaging.py skips itself unless import diagrams resolves to an installed copy, so run it from outside the unpacked tree or it will quietly test the source next to you.

The playground runs the real package under Pyodide

There is a browser editor at diagrams.mingrammer.com/playground that needs no Python and no Graphviz on your machine, because it is not a reimplementation. It runs the real diagrams package in the browser through Pyodide, which means what you see in the playground is what your local install does. It supports node search, autocompletion, export to PNG, SVG and JPEG, and shareable links. The limitation follows from the same architecture: everything runs client side, so a large diagram pays the full Python startup and layout cost in your tab, and a shareable link is carrying your architecture somewhere you have not audited. The docs split the material by task, with a quick start, a guides section for diagram work, and a per-provider node index that starts at the AWS node list.

The interesting users are projects that read real infrastructure

The listed consumers are not diagram artists, they are tools that turn something existing into a picture. Apache Airflow uses Diagrams to generate architecture diagrams in its documentation. Cloudiscovery analyses resources in a cloud account across AWS, GCP, Azure, Alibaba and IBM, then draws the resource map it found. KubeDiagrams builds Kubernetes architecture diagrams from manifest files, kustomization files, Helm charts and actual cluster state, supporting built-in resources, custom resources and label-based clustering. AWS CloudFormation Diagrams is a small CLI script that does the same for CloudFormation templates. Airflow Diagrams is a plugin that visualises DAGs at service level across providers such as AWS, GCP and Azure. The pattern is that the drawing is the last step, and the value sits upstream in whatever parsed the real system. If you have nothing to parse, the library is a layout tool.

Every dependency range is capped on both ends

The runtime dependencies are graphviz>=0.13.2,<0.22.0, jinja2>=2.10,<4.0 and typed-ast>=1.5.5,<2 restricted to python_version<'3.8'. That last marker is dead code against requires-python = "~=3.9", since the package cannot be installed on 3.7 in the first place, so you can ignore it while reading and know it will never resolve. The upper caps are the part to plan around. graphviz is held below 0.22, jinja2 below 4.0, and the dev tools are likewise bounded, with pytest>=8.3,<9, pylint>=3.3,<4, black>=24.4,<25 and pre-commit>=4.0,<5. Pinning keeps a build reproducible, but the ceilings mean a new major release of any of these either blocks your upgrade or forces you to work around the resolver.

Master has moved ten months past the newest release

The three most recent tags are v0.25.1 dated 2025-11-22, v0.25.0 dated 2025-11-21 and v0.24.4 dated 2025-03-10, and the master branch received a push on 2026-09-22. So the package index carries a release roughly ten months behind the branch, and pip install diagrams gets you v0.25.1, not what is on master. The repository keeps a CHANGELOG.md to bridge that gap, and a scripts/check_release_version.py that travels in the sdist so packagers can confirm a build matches its version. The rest of the tree explains the generator story: autogen.sh, config.py, templates/, resources/, website/, playground/, docker/ and a .devcontainer/ directory. If you need something newer than the published release, you are building from a checkout, not installing a wheel.

Editorial conclusion

Diagrams is the right tool when you want to argue about a design in a pull request and let Graphviz do the layout, and it is a poor substitute for anything that provisions infrastructure. Before adopting it, check that your CI image can install Graphviz, pin an exact version because dependency ranges are capped, and decide whether you need a node from a provider that is not in the list. If you need the output to be executable, this library will not get you there, and the Go port go-diagrams exists for teams writing Go rather than Python.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes