AWS Icons for PlantUML pins a service catalog to a release tag so your diagrams stop drifting

The repository is a generated artifact, not a hand drawn icon set

AWS Icons for PlantUML is a collection of PlantUML images, sprites, macros and other includes covering Amazon Web Services services and resources. The important detail is how it is produced. The README states that all elements are generated from the official AWS Architecture Icons, and that new releases are created when AWS updates that icon set, with the release tag similar to the release date from AWS.

That makes the repository a mirror of a vendor asset rather than a design project. The trade-off follows directly. You get accuracy against the current AWS icon set without drawing anything, and you accept that the timeline is AWS's timeline, not yours. A team that wanted custom icons for internal services, or wanted to match a house diagram style, will not find that here.

The repository layout matches the pipeline. A `source/` directory holds the inputs, `dist/` holds the generated output, `scripts/` and a `pyproject.toml` describe the generator, and `examples/` contains the sample diagrams with names that map onto the use cases: raw image usage, raw sprite usage, simplified views, technical views, group diagrams for VPC, Auto Scaling and CodePipeline, and a Serverless API example.

The generator is a Python project requiring Python 3.12 or newer, with `jinja2`, `pyyaml`, `lxml` and `pillow` as its dependencies and `pytest` in the dev group. The presence of `lxml` and `pillow` is a hint about the work involved: parsing the source icon metadata and rasterising images is not a trivial transformation.

Two include styles: one file per service or a whole category

Once `AWSCommon.puml` is loaded, resources are referenced in one of two ways. The first is an individual include file, one per service or setting, such as the simple storage service file under the Storage directory. The second is a category include file, a single include that pulls in every service and resource for that category, such as `all.puml` under BusinessApplications.

That choice is a real trade-off in file size and in control. A category include is one line and guarantees you have every icon in that area, at the cost of pulling in entities your diagram never draws. An individual include is precise and keeps the diagram source short, at the cost of knowing exactly which file holds which service.

The `dist/` directory is organised by service or product category, with the corresponding `puml` files inside. The `AWSSymbols.md` file at the repository root is the index that answers the question of which file holds a given service, and the `source/` directory is the place to look if you want to know what the generator actually reads.

For a large diagram the practical habit is to use individual includes and let the diagram grow by adding one line per service, rather than starting from a category and deleting what you do not need. The generated output is not a small file, and a diagram that includes a whole category will carry that weight into every render.

Pin to a release tag or your diagram changes under you

The README repeats one instruction in several places, which tells you the project has been burned by it. Include files by a specific release version, not by the `main` branch. The examples reference `v23.1`, the current release, and the documentation notes that using the main branch means the content can change without your diagram changing.

The mechanics are simple. You define a macro pointing at the root of the `dist` directory, include the common file from there, then include the resources you want.

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.1/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/BusinessApplications/all.puml
!include AWSPuml/Storage/SimpleStorageService.puml

The `AWSPuml` macro exists to shorten the lines. Without it every include repeats the full raw URL, which is long enough to dominate the diagram source.

Two things follow from this design that are worth being explicit about. First, the rendered diagram depends on a fetch to raw.githubusercontent.com unless you vendor the files locally, and the same `!include` statement works with a local path, which is the option for an air-gapped or offline rendering pipeline. Second, a diagram that pins v23.1 keeps rendering the same picture indefinitely, which is exactly what you want in a repository of architecture documentation, and exactly what you do not want if you were hoping icons to update silently.

Earlier versions of PlantUML required `!includeurl` for URLs. Now `!include` handles local paths and URLs alike, and the syntax `!include <awslib/AWSCommon.puml>` draws on the embedded plantuml-stdlib, which since PlantUML 1.2022.14 includes the Release 14-2022.07.31 icon set. That stdlib path is a fallback, and it is fixed, so it will not track the AWS icon set.

AWSCommon.puml sets the style, and the dark mode switch is experimental

The common include is the base. It defines the colors, styles and characteristics for the diagram, and it has to come before the resource includes, since the resource files assume those styles exist.

!include path/to/AWSCommon.puml

The project also offers an experimental dark mode, enabled by setting a variable before the common include. The examples carry the line commented out, ready to be uncommented.

@startuml Hello World
'!$AWS_DARK = true

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.1/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/BusinessApplications/all.puml
!include AWSPuml/Storage/SimpleStorageService.puml

actor "Person" as personAlias
WorkDocs(desktopAlias, "Label", "Technology", "Optional Description")
SimpleStorageService(storageAlias, "Label", "Technology", "Optional Description")

personAlias --> desktopAlias
desktopAlias --> storageAlias

@enduml

The component syntax visible in that example is worth reading once. Each AWS entity takes a name, then parenthesised arguments: a display label, a technology category and an optional description. The diagram example names in the repository confirm the pattern, with variants for simple view and technical view.

The word experimental appears in the README for the dark mode, and the example images are generated from the sources in the `examples` directory. Treat the dark theme as something to try rather than something to depend on in a published document, since a theme change alters every diagram that uses it and the flag may move or change behaviour between releases.

Customized builds are the answer when a diagram is too heavy

The README has a section on customized builds, alongside the distribution details. The examples directory contains a `theme-testing` folder and an `upgrade.sh` script, which is a reasonable indication of how a team would handle a new icon release across an existing corpus of diagrams.

For a team maintaining a few hundred diagrams, the realistic workflow is to vendor a chosen release's `dist` directory into the repository, point the `AWSPuml` macro at that local path, and then move to a new release in a single controlled commit. That gives you the reproducibility of a pinned tag and the offline behaviour of a local include, at the cost of storing the generated files yourself.

What the documentation does not spell out is how the customized build feature interacts with the upstream `dist` directory, and how the source inputs are structured for people who want to add a service that AWS has not published. The `source/` directory is the place to look, and the `pyproject.toml` shows the generator takes `jinja2` templates plus `pyyaml` and `lxml` parsed input, so adding an entry means working in that generator's data format rather than hand editing a `.puml` file in `dist`.

The `AWSSymbols.md` file at the root is a good place to confirm coverage before you commit to a service being available, and `examples/MarketplaceSaaS.puml` is a good place to see how a non core AWS offering is represented.

The licence needs reading before you embed the assets

The repository carries a licence that GitHub could not classify, and the authoritative text is in the `LICENSE` file. There is a second file, `LICENSE-CODE`, and the README header carries an MIT SPDX identifier with a copyright line for Amazon.com, Inc. or its affiliates. The README also has its own license summary section, which is the piece to read first.

The split into two files is a common pattern for a project that mixes code and a third party asset set, and it is exactly the kind of split where a careless assumption causes trouble. The generator code and the AWS icon assets are not obviously the same thing, and the rules for redistributing a PNG differ from the rules for redistributing a Python script. The README points at the AWS Architecture Icons as the upstream source of the graphics, so the AWS terms for those assets are part of the picture.

This is not legal advice, and the point here is narrow: read `LICENSE`, `LICENSE-CODE` and the README license summary before you paste these files into a diagram embedded in a customer facing document or into a product. The MIT identifier in the file header is a statement about a particular file, not a blanket answer for the whole repository.

One more point of order: the diagrams render by fetching from GitHub, so a document that embeds a rendered image is distributing AWS derived artwork, and a diagram that embeds the sprite files directly is distributing more of it.

Release cadence follows the AWS icon set, not your needs

The last push to the repository was on 2026-09-01, and the release tags show a rhythm driven by the upstream asset set. v23.1 was released on 2026-09-01, v23.0 on 2026-03-13 and v22.0 on 2026-03-11.

The two releases of March, two days apart, look like a preparation followed by a switch, and the numbering follows the AWS icon release rather than a semantic version contract. There is no changelog in the README describing what changed between icon sets, so the practical way to see what a new tag contains is to diff the `dist` directory yourself, and the `AWSSymbols.md` index is the fastest place to check whether a service appeared or was renamed.

The upgrade cost for a consumer is therefore an operational cost, not a code change. If you pinned v23.0 in three hundred diagrams, moving to v23.1 means editing those includes and reviewing the diff of every rendered image, because an icon change is a visual change and a reviewer will not notice it in the source diff. The `upgrade.sh` script in the examples directory is presumably aimed at exactly that, but the README does not describe its usage, so anyone planning a large migration will want to read the script before running it across a repository.

The project is not archived, and the last push was on 2026-09-01. Whether the next icon set arrives in three months or nine depends on AWS, and your diagrams should not care, which is the argument for pinning in the first place.

Editorial conclusion

Adopt AWS Icons for PlantUML if you draw AWS architecture as code and want the official icon set available through include statements rather than hand-drawn rectangles, and pin every diagram to a release tag such as v23.1. Do not adopt it if your diagram pipeline renders without network access and you have not vendored the dist directory, because the documented usage pulls the includes from raw.githubusercontent.com at render time. Verify first that the service you need exists in dist for the tag you chose, that the icon set matches the AWS Architecture Icons release you cite in your documentation, and that your renderer tolerates the include statements before you put a hundred diagrams in a repository.

Frequently asked questions

Official sources

1. awslabs/aws-icons-for-plantuml on GitHub
2. Issues
3. Project website
4. README
5. Releases