Godot project dependency graphs

Mon May 11 2026

(If you want to skip all the blah-blah and just want to know how to get the dependency graphs for a Godot project, just head down to the summary.)

So the other day I was deep in yet another refactor. I do enjoy the process for the most part. I really like taking a messy piece of code and not just hammering a feature on top of it, but also cleaning it up. Or to turn a feature that was added in haste, as an experiment, into a solid part of the system it lives in.

In general, I like leaving a place in a better state than I found it, although it's difficult to find the energy for that sometimes. Especially in refactoring, oftentimes you have to keep a lot of context in your head. You decide to update one thing, and you realize that it's about to untangle a whole web, and your promise of "it'll be done today" turns into "Ugh, yeah, I need more time," and back in the coding mines you go.

Anyway, I was deep in the trenches when I started thinking that I need to look at the big picture. And turns out that I can! Some kind soul has made a tool to create dependency graphs for Godot projects.

What's a dependency graph?

In case you're not familiar, a dependency graph is used to represent relationships between objects where directions indicate who depends on what, or, in the context of Godot, it represents relationships between gdscript classes. A quick example. A class Player has a Pocket (or multiple), which has an array of Item. It can be represented in a dependency graph like this:

Player → Pocket → Item

Meaning, Player has a direct dependency on Pocket and something that's called a transitive dependency on Item (meaning it depends on Item by proxy). That means if something in Item breaks, Pocket and Player will break too. This is an absurdly simple example, but I hope in case you didn't understand before now, you do!

In the "real world," dependency graphs are way more complicated. Sometimes an arrow will go across an entire graph, violating all boundaries, just because a developer had to rush a feature, so they took a shortcut and connected things that should have been decoupled. Sometimes arrows point in both directions, creating something that's called a circular dependency. Something silly like the Player has a Pocket, field which has a Medipak inside of it, which happens to have a reference back to the Player for some reason.

Dependency graphs are great because they highlight architectural problems and technical debt, which become more and more expensive to solve as workarounds get stacked on workarounds, because to pay the bills you've got to ship.

Graphing Godot projects

So, how do we get one for your Godot project?

First of all, you need to have gdscript's stepdad python installed. If you run Linux, it's very likely that you already have it installed. Open up a terminal (or Command Prompt on Windows) and type python --version. If it outputs something like "Python 3.14.4", which is what I have installed, you are good to go! The version number doesn't have to be exact. A recent version of Python 3 should suffice.

Before we can get graphs, we're going to have to:

• create and activate a virtual environment
• install the single dependency for godot_dependency_graph
• get the godot_dependency_graph scripts themselves

Let's start with the hard part if you're not a python developer - the virtual environment (say virtualenv if you want to blend in among python developers). It's basically a way to isolate a project's python packages from operating system packages (which is especially important for Linux since Linux distributions tend to come with python programs themselves and we don't want to accidentally break them). The easiest way to create and manage one is using a python package and project manager called uv, so go ahead and install that.

We need a folder to store our python scripts, so just create a folder with some name, like depgraph, and navigate to it from a terminal. Then initialize the virtualenv by using the venv subcommand of uv:

uv venv

It'll print out the command you need to activate the isolated virtualenv:

source .venv/bin/activate

After running that you'll see that your terminal prompt will be prefixed with the name of the current folder, which means that the virtual environment is active.

A note on the virtual environment—it's only active for the current terminal session, so to deactivate it, you can either close the terminal window or just type deactivate.

Now that your environment is ready, install the only dependency of the graph builder - GDScript Toolkit. On its own, it's a fucking Swiss Army knife; it can do linting, it can parse your gdscript into a tree structure and it can even analyze cyclomatic complexity (basically, how many paths code can take in a function). Install it with the following uv command:

uv pip install "gdtoolkit==4.*"

(use gdtoolkit==3.* in case you are running on Godot 3.x)

That should take no time at all. And now install the graph builder. If you have git installed, assuming you are in the depgraph folder or however you just happened to name yours, just clone the repository:

git clone https://github.com/crapola/godot_dependency_graph.git

Otherwise, you can just grab the ZIP. In case you do that, after extracting, rename its folder to godot_dependency_graph otherwise, python won't be able to find it.

Now you are set up to graph some dependencies. From the depgraph folder, run:

python godot_dependency_graph <path_to_godot_project>

If you did everything right, you're going to get a printout. If you get any errors, just make sure that a folder called godot_dependency_graph actually exists wherever you are running the command from and that you're pointing it to a folder that has a project.godot inside of it. You can also just save it straight to a file with the --output flag:

python godot_dependency_graph <path_to_godot_project> --output some-graph.dot

Now you need a graph visualization tool to actually see what the output represents. The graph builder repo itself recommends GraphvizOnline. Just paste in the graph output and behold the spaghetti! You can export to various image formats, so you can study it later. Or print it on a t-shirt and gift it to your SO.

The output should give you an idea of any issues you might have. Keep in mind that sometimes things are just fine even if the graph doesn't flow as nice. But I can't tell you how to do it. I'm definitely not qualified to teach someone how to refactor their project, but very smart people have written entire books about it.

Summary

So here are all the steps again to recap! They assume uv is installed (and that you're on Linux):

# create and navigate into a folder (the name is not important)
mkdir depgraph
cd depgraph

# create and activate a virtualenv
uv venv
source .venv/bin/activate

# install the gdtoolkit dependency for Godot 4
uv pip install "gdtoolkit==4.*"

# get the actual dependency graph generation scripts vai git
# (you can also just download the ZIP through github.com)
git clone git@github.com:crapola/godot_dependency_graph.git

# output the dependency graph
python godot_dependency_graph <path_to_folder_containg_your_godot_project>

# or output it as a file
python godot_dependency_graph <path_to_folder_containg_your_godot_project> --output some-graph.dot

Then you can feed the output into something like GraphvizOnline!

Keep in mind that every time you want to use the dependency graph builder afterwards, you have to activate the virtual environment!

Good luck refactoring!

I'll use the opportunity to mention that the site is now on European soil—I migrated from AWS to Hetzner i.e., from Netlify to statichost.eu. Seems like a good service, with a nice, minimalistic, clean dashboard. I had to change DNS servers for this, which, as I realized only way later, broke my Bluesky handle. Would have been nice to get some form of notification. Life is hard, I guess. If you have a tip or opinion you want to share, you're welcome to do so over on Bluesky or Mastodon!