Introduction

The best way to generate UML from Python source depends on what you need from the diagram. If you want a quick class and package overview straight from the codebase, a static analysis tool such as pyreverse is usually the most practical starting point. If you want polished architecture diagrams, you often generate a first draft from code and then refine it manually.

Why Python Makes This Tricky

Python is dynamic, so no tool can perfectly infer every runtime relationship from source alone. Static generators work well for:

• class inheritance
• module and package dependencies
• obvious composition relationships

They work less well for:

• dynamic attribute creation
• runtime monkey patching
• metaprogramming-heavy frameworks

That means the "best" tool is usually the one that gets you a useful draft quickly, not one that promises a perfect diagram of every dynamic behavior.

A Practical Default: pyreverse

pyreverse ships with pylint and is a common first choice for Python UML-like class diagrams.

Install it if needed:

python -m pip install pylint

Then run it against a package or module:

pyreverse -o png -p myproject src/myproject

That command tells pyreverse to:

• inspect the package
• generate diagrams
• emit PNG output
• label the project as myproject

Depending on the version and environment, it may also generate intermediate Graphviz .dot files that can be useful for further editing.

A Small Example

Suppose the codebase contains:

1class Animal:
2    pass
3
4
5class Dog(Animal):
6    def bark(self) -> str:
7        return "woof"
8
9
10class Kennel:
11    def __init__(self, dog: Dog) -> None:
12        self.dog = dog

A static UML generator can usually infer:

• 'Dog inherits from Animal'
• 'Kennel holds a relationship to Dog'

That is exactly the sort of structure these tools are good at extracting automatically.

Use Graphviz-Friendly Workflows

Many Python UML tools either produce Graphviz output directly or rely on Graphviz for rendering. That is useful because Graphviz makes it easy to:

• export PNG or SVG
• tweak layout manually
• integrate into documentation workflows

So even if your final tool is not pyreverse, choosing a generator that fits a Graphviz pipeline is often a good idea.

When to Use PlantUML or Manual Refinement

For architecture diagrams that people will actually read in design documents, fully automatic output is often too noisy. A better workflow is:

1. generate a rough diagram from code
2. remove irrelevant classes and modules
3. redraw or refine the important relationships

That is where tools such as PlantUML become useful. Instead of trusting the generated diagram blindly, you turn the generated structure into a curated diagram that communicates intent.

Automatic generation is best for discovery. Manual refinement is best for communication.

What "Best" Usually Means in Practice

In day-to-day engineering, "best" usually means:

• fastest to run
• easy to regenerate
• good enough to expose structure

That is why pyreverse remains a solid answer for many Python teams. It is easy to try, requires little ceremony, and gives immediate feedback about package and class relationships.

If the project is highly dynamic, no generator will save you from some manual modeling. In that case, the best tool is the one that gets you a starting point with minimal effort.

Common Pitfalls

• Expecting a static tool to model all dynamic Python behavior perfectly.
• Treating the generated diagram as documentation-quality output without trimming or refining it.
• Forgetting that huge codebases can produce diagrams that are technically accurate but unreadable.
• Choosing a UML generator before deciding whether you need discovery, documentation, or communication.
• Skipping Graphviz or rendering dependencies and then blaming the Python tool for incomplete output.

Summary

• For Python source code, a practical default is to generate a first UML-style draft with pyreverse.
• Static analysis tools work well for inheritance and obvious code structure, but not for every dynamic runtime behavior.
• Graphviz-friendly workflows are useful because they make rendering and refinement easier.
• Auto-generated diagrams are best for discovery; curated diagrams are better for communication.
• The best approach is usually a combination of automatic extraction and selective manual cleanup.