GDScript Formatter: The fast formatter for Godot 4

We've built a new code formatter for GDScript, written in Rust, that's fast and easy to use: GDScript Formatter. This formatter formats files in up to a couple dozen milliseconds on a mid-range laptop, which means your code gets formatted almost instantly.

GDScript Formatter formats your code in a snap:

open in new tab

The formatter handles all the core formatting you expect: consistent spacing, indentation, and good vertical spacing between functions and classes, all according to the official GDScript style guide.

It can optionally also reorder your code to match the style guide, moving all the signals and variables at the top, then built-in Godot methods, then public and private methods, and so on.

Here the variables are between function definitions. The formatter moves them instantly to the top:

open in new tab

Use with caution!

I recommend using a version control system like Git before integrating this formatter on your projects and running it on every file.

While we use it in production work at GDQuest, GDScript is a complex language with many different syntax patterns. A formatter for this kind of language is a complex beast. There are always edge cases, and the formatter may not handle all the syntax (like rare syntax or brand new syntax from development versions of Godot).

So, having a backup of your code or a way to undo is always a good idea.

Installing the formatter

To install the formatter, first download the executable file for your operating system from the links at the bottom of the page. Then, rename the file to something simple like gdscript-format and place it in your system PATH.

What is the PATH?

The "PATH" is a variable on your operating system. It contains a list of folders where your computer looks for programs when you type commands in the terminal. When you use a code editor and it runs external programs, these programs come from the PATH.

When you put the formatter in one of these "PATH" folders, you can run it from anywhere on your computer by just typing its name. On Windows, common PATH folders include C:\Windows\System32 or you can create a bin folder in your user directory. On macOS and Linux, you can use ~/.local/bin or /usr/local/bin.

You can also add a new folder to your PATH if you prefer to keep your tools organized in a specific place. How to do this depends on your operating system and terminal shell program. I recommend looking up a guide specific to your computer on your favorite search engine like "how to add a folder to PATH on Windows 11" or "how to add a folder to PATH on Ubuntu 24.04".

Using the formatter

Once you have the formatter installed, to use it, open your terminal or command prompt and type:

gdscript-format path/to/your_script.gd

This command will format your file and save the changes directly to the file.

For extra safety, you can use the --safe flag to add a protection check that prevents the formatter from overwriting your files if it makes unwanted changes. This includes any change that could modify what your code actually does, like accidentally removing a piece of working code:

gdscript-format --safe path/to/your_script.gd

This safety check is especially useful when you're using a development version of the formatter or when you want to be extra careful with important code files. If the formatter detects that it might have changed the meaning of your code, it will stop and leave your original file unchanged.

If you want to check if a file needs formatting without changing it, you can use the check mode:

gdscript-format --check path/to/your_script.gd

The check mode is particularly useful for build systems or continuous integration. It will exit with code 1 if the file needs formatting, making it easy to enforce consistent code style in your projects.

Experimental: You can also reorder your code according to the official style guide by adding the --reorder-code flag. This formats your code and rearranges it to follow the recommended order from GDScript's official style guide:

gdscript-format --reorder-code path/to/your_script.gd

Formatting on single vs multiple lines

This formatter works differently from some other code formatters you might have used. Instead of automatically wrapping long lines at a specific character limit, it gives you control over how your code is formatted.

The formatter uses cues from your code to decide whether to format something on one line or multiple lines. For example, if you write this:

var numbers: Array[int] = [1,2,3,4,5]

The formatter will clean up the spacing but keep it on one line:

var numbers: Array[int] = [1, 2, 3, 4, 5]

But if you write this with a line break:

var dialogue_items: Array[String] = ["First line...",
"Second line...", "Third line..."]

The formatter will wrap it across multiple lines:

var dialogue_items: Array[String] = [
	"First line...",
	"Second line...",
	"Third line..."
]

Why not automatically wrap long lines?

Automatic multiline formatting in a language like GDScript is really difficult to get right. This formatter is designed to be a stop-gap solution until we get an official formatter built into Godot.

Instead of giving you an automatic behavior that sometimes works and sometimes doesn't, this approach keeps you in control: you decide how you want your code to wrap. The formatter will follow your lead and make sure the spacing and indentation matches the style guide.

Code editor integration

Here are step-by-step instructions for setting up the formatter in different editors:

Zed

Zed is a new code editor by the creators of Atom, written in Rust.

To use the formatter in Zed, first install the zed-gdscript extension. This extension adds Godot and GDScript support to the program.

Once you have the extension installed, you can configure the GDScript language to use GDScript Formatter on save or when running editor: format. Add this to your settings.json file (you can open it with the zed: open settings command from the command palette):

{
  "languages": {
    "GDScript": {
      "formatter": {
        "external": {
          "command": "gdscript-format"
        }
      }
    }
  }
}

If you renamed the formatter binary to something else, change the command name to match. Once this is set up, Zed will automatically format your GDScript files every time you save them. If automatic formatting doesn't work, check that format_on_save is set to true in your settings (this is the default). You can also format manually by running the editor: format command in Zed.

To run the formatter with extra options, like --safe or --reorder-code, you can add an args array to the configuration:

{
  "languages": {
    "GDScript": {
      "formatter": {
        "external": {
          "command": "gdscript-format",
          "args": ["--safe"]
        }
      }
    }
  }
}

NOTE:

I recommend using the --safe flag if you want extra protection against unwanted changes. And for the --reorder-code flag, I would suggest using it manually as a task you run from your command palette, rather than automatically on every save.

Helix

Helix is a modal text editor that runs in your terminal, inspired by Kakoune and Neovim, built in Rust.

First, make sure you've installed the formatter and it's in your system PATH. Then you need to edit Helix's language configuration file. Navigate to your Helix config directory and open the languages configuration from your terminal:

cd ~/.config/helix && hx languages.toml

Add this line inside your [[language]] block for GDScript:

formatter = { command = "gdscript-formatter", args = ["--safe"] }

NOTE:

Using GDScript with Helix requires additional setup beyond just the formatter. You'll need to configure the language support and possibly set up Godot to work with external editors.

To enable automatic formatting when you save files, add this line to your GDScript language options:

auto-format = true

Use this option mindfully, as it will format your code every time you save. Be sure to use a version control system and the --safe option to limit unwanted changes and be able to revert them.

JetBrains Rider

Rider is a proprietary development environment from JetBrains that supports many programming languages, including GDScript.

After installing the formatter, open Rider and go to your IDE settings. Look for Tools > File Watchers in the settings menu. Click the + button to add a new file watcher and select from the dropdown.

Fill in these configuration fields:

• Name: GDScript Formatter
• File Type: GDScript
• Scope: Current File
• Program: gdscript-format (or the full path if it's not in your PATH)
• Arguments: $FilePath$ or $FilePath$ --safe if you want extra protection
• Output Paths to refresh: $FilePath$
• Working Directory: $ModuleFilePath$

You can turn on the boxes for auto-save and triggering when files change outside the editor if you want. Make sure to keep the "Create output file from stdout" box unchecked.

If the formatter accidentally changes something you didn't want, you can usually undo with Ctrl+Z (or Cmd+Z on macOS). This will show you an "undo reload from disk" option. You can also check the local history by right-clicking on the file and selecting Local History > Show History.

Can I use this from within Godot?

GDScript Formatter is not available in Godot yet. But we're planning to make it available as a Godot add-on in the near future. Keep an eye on this task on the project's code repository for updates!

Contributing and getting help

We need your help to make this formatter even better! GDScript has grown into a complex language with many different syntax patterns, and we want to make sure the formatter handles all of them correctly.

You can find the complete source code and contribute to the project on our GitHub repository. The repository includes detailed information about how to contribute, build the project from source, and submit improvements.

Found an issue? Please share the problematic code snippet with us by creating an issue on GitHub. When you report problems, it helps us improve not only this formatter but also the Tree Sitter GDScript parser that powers GDScript support in code editors like Zed, Neovim, and Emacs.

Even if you're not ready to contribute code, testing the formatter on your projects and reporting any issues you find is really valuable for the entire GDScript community!

Here's a template you follow to report issues:

You can use the following template as a reference when reporting issues on GitHub to help us understand and fix the problem:

Input code (the code that the formatter didn't handle well):

func check(x: bool): print(x)
var test

Current output (how the formatter actually formatted the code):

func check(x: bool):
	print(x)var test

Expected output (how the formatter should format the code):

func check(x: bool):
	print(x)


var test

Please share minimal code snippets like this that reproduce the issue if you can. It helps to narrow down the rule or syntax pattern that needs a fix.

Download files

• Download for Windows x64
• Download for Linux x64
• Download for macOS ARM64

If you need a version for a different system architecture, you can find all available downloads on the latest release page.