This user manual covers how to install and use the GDScript Formatter directly from within Godot 4. The formatter helps you keep your code clean and consistent by automatically fixing spacing, indentation, and code order, while the linter catches common style issues (all according to the official GDScript style guide).
This documentation guides you through everything you need to know to improve your code quality and save time on manual formatting.
In this guide, you'll learn how to:
The formatter comes in two parts: the Godot add-on and the formatter binary. The add-on adds menus and commands to Godot, while the binary does the actual formatting work. You need both to use the formatter.
First, you need to add the add-on to your Godot project:
res://addons/gdscript_formatter/The add-on is now active and will add a "Format" menu to the script editor.
The GDScript formatter is a native computer program written in Rust, so just like Godot, it needs a different executable on Windows, macOS and Linux to work.
The add-on can download and install the correct version for your system automatically:
Then, wait for the small download to complete. You'll see messages in the Output bottom panel to show the progress.
The add-on downloads the formatter and puts it in Godot's cache folder. You only need to do this once per computer. If you see an error, check your internet connection and try again.
Yes! If you already have the formatter installed on your system, you can tell the add-on where to find it:
For example, if you installed the formatter globally on your computer, you might set this to just gdscript-formatter.
Once the formatter is installed, you can use it to clean up your code whenever you need. You have several ways to run the formatter depending on your workflow.
The most common way to use the formatter is to have it automatically format your code every time you save:
Now, every time you save a GDScript file with , the formatter will format your code.
You can format your current script manually in three ways:
The formatter can also reorder the elements in your script to follow the GDScript style guide.
To reorder your current script:
Your code elements will be rearranged to follow the official style guide order. This is a separate command from regular formatting because it changes more of your code's structure. You may want to use the command to do a big cleanup in a large script, and then reorder a few elements manually to fine-tune it.
You can also enable automatic reordering in Editor
Important: Code reordering cannot always perfectly reorder your code while preserving your intentions. We favor following the official style guide. So if you want to make code regions that group certain elements together, you may need to reorder those manually after running the command. I recommend using the reorder command manually for this reason, rather than enabling automatic reordering on save.
Yes! You can press ctrlz (on Mac: ⌘z) immediately after formatting to restore your code to how it was before.
The formatter follows the official GDScript style guide, so most changes are intentional to keep your code consistent with Godot's standards.
If you find a change that is not part of the style guide or that breaks your code, please report it as an issue on the formatter's GitHub repository (this link lists existing issues to avoid duplicates). Please include a code snippet showing the before and after so we can investigate and fix it.
The linter checks your code for style issues without changing anything. It highlights style problems in your script and shows you detailed messages about what needs fixing in the Output bottom panel.
To check your current script for linting issues:
The linter runs and shows results in two places:
Red markers mean errors, yellow markers mean warnings.
Just like formatting, you can have the linter check your code automatically every time you save:
Now, every time you save a GDScript file, the linter highlights any issues in your editor and prints a summary in the Output
The lint highlights stay in your editor until you run the linter again or format the code. To clear them:
Yes! You can enable both settings. When you save a file:
This combination gives you automatically clean code that also passes style checks. Formatting happens first, so the linter sees and checks the formatted version of your code.
All formatter settings are in Editor
The Formatter Path
By default, after auto-installation, this points to the formatter in Godot's cache folder. You might want to change this if you installed the formatter globally on your computer.
To change it:
Use just gdscript-formatter if it's in your system's PATH, or use the full path to the executable otherwise.
By default, the formatter uses tabs for indentation. You can change this to use spaces instead:
If you want the formatter to always reorder your code elements:
Now, every time you format (including format on save), the formatter will rearrange your code to follow the GDScript style guide order.
Important: You cannot use both Reorder Code
Safe mode makes the formatter more conservative. It verifies that the code is valid before making changes, which can prevent some issues in complex scripts. To activate safe mode:
Important: Safe mode is not 100% fail-proof. It greatly reduces the risk of errors, but cannot guarantee that no issues will ever occur. It should however work reliably on the majority of Godot projects (the risks are mainly with rarely used or newer syntax that the Rust GDScript parser does not support yet).
The linter can check if your lines are too long. By default, it warns about lines longer than 100 characters:
The GDScript style guide recommends keeping lines under 100 characters for readability. Feel free to increase this if you work on a large monitor.
If you want the linter to skip certain rules, you can add them to the ignore list:
For example, if you don't want to see warnings about line length, you could enter line-too-long. If you want to ignore multiple rules, use commas: line-too-long,another-rule.
The linter will skip any rules you list here when checking your code.
You can change the format shortcut to whatever you prefer. It uses the same ShortCut resource used by UI nodes in your Godot projects:
The default is Ctrl+Alt+I (or Cmd+Alt+I on Mac), but you can change this to any key combination that doesn't conflict with other Godot shortcuts.
The formatter binary gets updated regularly with bug fixes and improvements. You can update it anytime or uninstall it if you no longer need it.
To get the latest version of the formatter binary:
The add-on downloads the newest version and replaces your current one. You'll see messages in the Output panel confirming when the download is complete.
If you want to remove the formatter binary that the add-on installed:
This removes only the binary from Godot's cache folder. The add-on itself stays installed and active in your project, it just won't be able to format code until you install the formatter again.
Don't stop here. Step-by-step tutorials are fun but they only take you so far.
Try one of our proven study programs to become an independent Gamedev truly capable of realizing the games you’ve always wanted to make.
Get help from peers and pros on GDQuest's Discord server!
20,000 membersJoin ServerThere are multiple ways you can join our effort to create free and open source gamedev resources that are accessible to everyone!
Sponsor this library by learning gamedev with us onGDSchool
Learn MoreImprove and build on assets or suggest edits onGithub
Contributeshare this page and talk about GDQUest onRedditYoutubeTwitter…
Site in BETA!found a bug?