Control package layout in class diagram

Question

I am trying to translate an Enterprise Architect diagram to PlantUML, because the EA expert has moved to another job (and licenses are scarce).

The diagram has 10 packages. I have a .puml file defining the packages, and the relationships between them. The .puml file pulls in !include files for all the classes/interfaces in the packages.

The default layout seems to be all the packages side by side as far as the .png will stretch (the rightmost package is truncated and there are a couple not shown at all) with all the arrows in a bunch of spaghetti across the top of the packages.

Now, it is possible to see the relationships between the packages if the packages were laid out in 3 columns, with service users in the left column, intermediate API packages in the middle and service providers in the right column. But I have not been able to make the layout program do this.

I tried using .right.> .up.> and .down.> to influence the layout but it seems a bit random whether the diagram accepts these suggestions or not.

I also tried using together {..} around the definitions of some of the packages, I ended up with quite a broken diagram, with some classes no longer in their proper packages. The manual does show together {...} being used for classes, not packages, so that's probably to be expected, so I gave up on together {...}

Using left to right direction and !pragma layout smetana changes the layout, but not in a way that makes the relationships readable. At least the "left to right direction" stopped the direction from being left to right and lined up the packages vertically, so they were all visible. But the arrows were still like spaghetti.

Changing the order in which the packages are defined has some influence on the layout. Why would this be? Surely the important thing is the relationships, so if there is no way for me to explicitly control the layout, the arrows should be what defines it?

(Note, I am drawing these arrows between the packages, not between the classes.)

Comments

Graphviz and Smetana layout engines both ignore the directed arrows. ELK respects them, and its layout looks very tidy, but it seems to be missing background colours and curved arrow lines.

---

Thanks, I hadn't noticed elk in the reference manual, my copy of PlantUML is perhaps a little old (dated 2025).

I wanted to see what Elk would do for me before upgrading -- upgrades are never risk-free -- so I tried using the online viewer at www.plantuml.com. I copied my source in there and got a diagram. Then I tried putting

!pragma layout elk

at the top, on lthe line after @startuml. Unfortunately the diagram disappeared and I got:

An error has occured : java.lang.IllegalArgumentException: java.lang.UnsupportedClassVersionError: org/eclipse/elk/graph/util/ElkGraphUtil has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0 (unable to load class [org.eclipse.elk.graph.util.ElkGraphUtil]) There is no problem so bad you can't make it worse

(this is not copy/pasted because the message comes as an image with text I need my extra-strong glasses to read.)

I'll try putting it in https://plantuml.com/qa

---

It's related to the Java version installed on your machine.

You need Java 17 to run ELK.

Hope this helps!

---

Fair enough, but that's why I was trying the diagram on plantuml.com instead of on my machine - upgrading PlantUML on my machine might need an upgrade of other stuff, like Java, and I worried that I might end up with a non-working PlantUML. So plantuml.com seemed safer - the image gets generated on the server there, right? So it should work...

Answer 1

Hello A.,

• What is your arrow type?

First:

• Can you try `-->`?

Second:

• Can you use arrows between classes?

If that can help,
Regards,

Th.

Comments

From:

To:

Enjoy,
Regards,
Th.

---

Thank you for your response! It's a good hint.

Drawing arrows between classes would change the meaning of the diagram so I would prefer not to do that. It would be like, in a state diagram, transitioning from a state instead of from its superstate.

Since the actual diagram is owned by my employer, I have made a diagram with anonymised names to indicate the problem.

I hope these links will work, using the live render site at plantuml.com

What is my arrow type? I want dashed lines with simple arrowheads, so .>

The first diagram is like this:

You can see the spaghetti at the top; also, about two and a half packages are not in the image.

I tried changing to --> and it does improve things a little:

At least now some of every package is visible, although one is still truncated. That's why when I tried it yesterday, I did not think it was a solution.

But if I also add left to right direction, it gets close to what I want:

The improvement is there with ..> instead of --> so that will be good enough, I think.

But I wonder why there is no syntax to influence placement, in PlantUML generally? The guy who did the EA work laid the packages out so there is no crossing of arrows so it's fairly legible, something like this:

"Package 1"    "Package 4"
               "Package 5" 
               "Package 6" 
"Package 2"    "Package 7"     "Package 10"
               "Package 8"
               "Package 9"
"Package 3"    

(hope that comes out legibly!)

I sort of assumed GraphViz is supposed to work out a placement that minimises the crossing of arrows, or something... and often it is quite good, but sometimes not. And I could save it the bother and just tell it, if there was a way to do so.

I tried changing some of the arrows from .> to .up.> etc. to try to control the placement of packages, and anything else I could think of :) but it feels a bit like I'm not allowed to say what it should do, only to hint at it. 

Frank

---

Actually, if I comment out all the classes, the layout is perfect, and all the relationships are clearly visible.

I also reversed the direction of the arrows to Package 2, instead of

"Package 1" ..> "Package 2"
"Package 3 ..> "Package 2"

it's 

"Package 2" <.. "Package 1"
"Package 2" <.. "Package 3"

Subtle hints to change the layout!

But it looks like the size of the images of the packages was what was causing the problem. Removing the classes makes them smaller, and the layout is much better.

I'll have to see if I can find a way to just list the names of the classes, that might make the packages small enough for the diagram to work. Losing the classes altogether seems a bit drastic.

Frank

---

I am having similar problems with PlantUML ignoring hidden directed arrows intended to align large packages vertically. I made a minimal reproducible example for you:

@startuml minimal_repro

top to bottom direction
hide members

package Alpha {
  package A {
    class A0
    class A1
    class A2
  }
}

package Beta {
  package B {
    class B0
    class B1
    class B2
  }
}

package Gamma {
  package G {
  }
}

Alpha -[hidden]d- Beta 
Beta -[hidden]d- Gamma

@enduml

These packages render side by side, unless you remove any class. Package nesting seem to be a precondition for reproducing.

PlantUML version 1.2026.3beta1 / ec2043b [2026-02-27 22:27:20 UTC]
(BSD source distribution)

Build Version: 1.2026.3beta1
Git Commit: ec2043b
Compile Time: 2026-02-27 22:27:20 UTC

Java Runtime: OpenJDK Runtime Environment
JVM: OpenJDK 64-Bit Server VM
Default Encoding: UTF-8
Language: en
Country: CA

PLANTUML_LIMIT_SIZE: 4096

GraphViz: dot - graphviz version 2.44.1 (20200629.0846)
Installation seems OK. File generation OK

---

Hello D.,

In order to align, just suppress the hidden arrow, from:

to:

Enjoy,
Regards,
Th.

---

The goal is to arrange them vertically, with Alpha on top, Beta in the middle, and Gamma on the bottom. That is the reason for having the hidden arrows. The bug is in PlantUML ignoring the arrows and laying out the packages side by side.

This is intended to be a minimal reproducible example. In my actual diagram, with hundreds of classes, PlantUML is stacking three already wide packages horizontally to make a very wide diagram.