Package Diagram
Use when asked to model the high-level organization of a system into packages/modules and their dependencies — as the highest-abstraction structural UML diagram, sitting above class diagrams (see class-diagram) rather than showing individual classes. See plantuml for the text-based syntax to actually draw one.
A package diagram is a UML static structure diagram showing how the packages that make up a software system are organized and arranged. A package is a container grouping similar classes, interfaces, and other elements together, providing a higher level of abstraction than a Class Diagram shows on its own.
Purpose
Gives an overview of system architecture, component organization, and dependencies — represented as a hierarchical structure, with a top-level package containing sub-packages and, ultimately, classes. It's the coarsest-grained structural view in this diagram family, deliberately omitting individual class detail to keep the whole system's module organization visible at a glance.
Notation
Packages are drawn as rectangles with a small tab on the upper-left corner (like a manila folder), with the package name written inside. Dependencies between packages are shown as directed arrows, indicating which package depends on which — a package diagram's dependency arrows are one of its most useful features, since they surface architectural coupling that's invisible from any single class diagram.
Why it matters for larger systems
Particularly useful for complex systems with multiple interacting modules — helping identify relationships between different parts of the system, making the software architecture easier to understand and maintain. It also supports organizing classes into logical groups for easier navigation, and enables separation of concerns: individual packages can be developed and tested in isolation without the whole system needing to be understood at once.
Drawing one
See PlantUML Diagram for the @startuml package-diagram syntax (package "Name" <<Stereotype>> { ... }) to generate one from version-controlled text.
Common pitfalls
- A dependency graph with cycles — two packages depending on each other in both directions is a common architectural smell a package diagram makes visible; treat a cyclic dependency as something to actually fix, not just document (see Fitness Function Testing for automating a check against this).
- Packages that don't actually group related elements — a package that's just an arbitrary bucket, rather than a genuine cohesive grouping, defeats the abstraction benefit the diagram is meant to provide.
- Showing individual classes in what should be a package-level view — mixes abstraction levels; keep package diagrams at the package granularity and push class-level detail into a separate Class Diagram.
Learn more
- PlantUML Diagram for the text-based syntax to draw this diagram type.
- Class Diagram for the finer-grained structure inside each package.
- Fitness Function Testing for automating an ongoing check against unwanted package-dependency direction or cycles.