Install & Compatibility
Where this runs
tested against v0.1.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.012s · 97.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.3s · import 0.008s · 98MB
101MB installed
● package 101MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Workspace
✓ from pystructurizr.dsl import Workspace
✗ from pystructurizr import Workspace
Core DSL components like Workspace, Person, SoftwareSystem, Container, etc., are located in the `pystructurizr.dsl` submodule, not directly under `pystructurizr`.
This quickstart demonstrates how to define a basic C4 model with a software system, containers, and relationships using PyStructurizr's DSL. It includes a basic `Workspace`, `Model`, `Person`, `SoftwareSystem`, `Container`, and `ContainerView`. The `with` syntax is used for hierarchical structuring.
from pystructurizr.dsl import Workspace
with Workspace(name="MyArchitecture") as workspace:
with workspace.Model(name="model") as model:
user = model.Person("User", description="A human user.")
with model.SoftwareSystem("Software System", description="My awesome software system.") as software_system:
webapp = software_system.Container("Web Application", description="Serves the user interface.")
db = software_system.Container("Database", technology="PostgreSQL", description="Stores data.")
user.uses(webapp, "Uses")
webapp.uses(db, "Reads from and writes to")
# Create a view onto the model
workspace.ContainerView(
software_system,
"My Container View",
"The container view of our simple software system."
)
# To save the workspace as Structurizr DSL (requires Structurizr CLI or compatible tool to render)
# workspace.save(format='dsl', path='./output')
# To save as SVG (requires an internet connection for Kroki.io)
# workspace.save(format='svg', path='./output')
print("Workspace 'MyArchitecture' created successfully. You can extend it or use the CLI to save/generate diagrams.")
pystructurizr --version
Debug
Known issues
breakingThe `Group` functionality and the `with` syntax for defining nested elements were introduced in version `0.1.3`. Code written with these features will not run on earlier versions (v0.1.2 and below).fixUpgrade to `pystructurizr>=0.1.3` using `pip install --upgrade pystructurizr`.
affects: < 0.1.3
gotchaPyStructurizr primarily outputs in Structurizr DSL format, not directly in Structurizr JSON schema. Some newer Structurizr rendering tools or integrations might expect the JSON format, leading to potential compatibility issues.fixIf direct JSON output is required, the generated DSL might need to be converted using official Structurizr tools, or alternative Python libraries that output JSON directly should be considered. Ensure your rendering tools are compatible with Structurizr DSL.
affects: All versions
gotchaWhen using the `pystructurizr` CLI to generate SVG diagrams (e.g., `workspace.save(format='svg')`), the diagram code is sent to an external online service (`kroki.io`) for rendering. Be aware of potential privacy implications if your architectural diagrams contain sensitive information.fixFor sensitive diagrams, consider using offline Structurizr rendering tools after generating the DSL, or review `kroki.io`'s privacy policy. The `pystructurizr` README mentions this behavior.
affects: All versions with CLI SVG generation
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pystructurizr.Workspace'
Attempting to import core DSL classes (like `Workspace`, `Person`, `SoftwareSystem`, etc.) directly from the top-level `pystructurizr` package instead of its `dsl` submodule.
fixCorrect the import statement to target the `dsl` submodule: `from pystructurizr.dsl import Workspace`.
AttributeError: 'Model' object has no attribute 'Group' or SyntaxError: invalid syntax (related to `with Group(...)`)
Using features like `Group` elements or the `with` syntax for hierarchical definitions, which were introduced in `pystructurizr v0.1.3`, with an older version of the library.
fixUpgrade `pystructurizr` to the latest version: `pip install --upgrade pystructurizr`.
Rendering tool complains about unsupported format or invalid input when trying to display diagrams from pystructurizr output.
The output of `pystructurizr` is Structurizr DSL, which might not be directly compatible with all Structurizr rendering tools, especially those expecting the Structurizr JSON format.
fixVerify that your chosen rendering tool explicitly supports Structurizr DSL. If not, you may need to use an official Structurizr tool to convert the DSL to JSON, or use the `pystructurizr` CLI's built-in SVG export which leverages `kroki.io` for DSL rendering.
Upgrade
Version history
0.1.3latest on PyPI · released Jul 27, 2023
Audit
Dependencies
No dependency data recorded yet.