Get featured

Upgrade a Godot 3 project to Godot 4: the converter first, then AI for the rest

Guide · checked against the docs on

You have a Godot 3 project and want it on Godot 4. It's tempting to paste every script into an AI tool and ask it to rewrite them. Godot ships its own project upgrade tool, though, and it handles the mechanical renames. This guide sums up what the official Godot docs say about that tool, as read on October 16, 2026, and where an AI tool fits after it. Nothing here is a hands-on test.

Not affiliated with or endorsed by the Godot Foundation or the Godot Engine project. If this guide and the Godot docs ever disagree, trust the docs.

Starting a new Godot 4 feature instead? See how to use AI to build a Godot 4.5+ feature.

Step 1: Decide whether to upgrade at all

The upgrading guide says: "Before beginning the upgrade process, it's worth thinking about the advantages and disadvantages that upgrading would bring to your project." (checked Oct 2026)

On the plus side, it says "4.x will enjoy a longer support period." (checked Oct 2026) On the other side: "If you don't need any features present in Godot 4.x, you may want to stay on Godot 3.x" (checked Oct 2026). It also warns: "Since Godot 4 is a complete rewrite in many aspects, some features have unfortunately been lost in the process." (checked Oct 2026)

Our advice, not a vendor quote: read that page's list of disadvantages and caveats before you start, especially if you target the web, old hardware or C# on mobile.

Step 2: Back up first

The docs are blunt: "Make a full backup of your project before upgrading!" (checked Oct 2026) And: "The project upgrade tool will not perform any backups of the project that is being upgraded." (checked Oct 2026) They suggest you "backup a project by using version control, or by copying the project folder to another location." (checked Oct 2026)

Our advice, not a vendor quote: commit everything to Git, then do the upgrade on a new branch. New to Git? Start with git basics for AI coders.

The docs also note: "Only Godot 3.0 and later projects can be upgraded using the project conversion tool found in the Godot 4 editor." (checked Oct 2026) They recommend you "ensure that your project is up-to-date with the latest 3.x stable release before running the project upgrade tool." (checked Oct 2026)

Step 3: Run Godot's project upgrade tool

In the Godot 4 Project Manager, you import the Godot 3 project and open it. The docs say: "You will see a dialog appearing with two options: Convert project.godot Only and Convert Full Project." (checked Oct 2026) They say to choose Convert Full Project, and that "Convert project.godot Only is intended to be used for advanced use cases only, in case the conversion tool fails." (checked Oct 2026)

There's also a command-line route. The docs say "it's recommended to validate the project conversion" (checked Oct 2026) first, using the --validate-conversion-3to4 argument, and then to run --convert-3to4 "If the list of planned upgrades looks good to you" (checked Oct 2026). The exact command is on the upgrading page.

The tool has limits on file size (in kilobytes) and line count. The docs say: "If a file hits either of those limits, it will not be upgraded by the project converter." (checked Oct 2026)

Our advice, not a vendor quote: let Godot's tool do the renames. Don't ask an AI tool to redo work the converter already does.

Step 4: Expect errors, and fix them in small pieces

The docs say what comes next: "Scripts will likely contain various errors as well (possibly hundreds in large projects)." (checked Oct 2026) That's because "the project upgrade tool cannot cater to all situations. Therefore, a large part of the upgrade process remains manual." (checked Oct 2026)

This is where an AI tool can help. The upgrading page lists changes the converter doesn't fully handle, for example:

Our advice, not a vendor quote: fix one script or one error type at a time. Give the AI tool the error message, the script and the matching section of the upgrading page, and tell it you're on Godot 4. Then run the project and check that error is gone before you move on. Commit after each fix, so you can undo a bad one.

A prompt you could adapt (we haven't tried it ourselves):

This project was just converted from Godot 3 to Godot 4 with Godot's
project upgrade tool. I'm on Godot 4. Fix only this error in this one
script. Use Godot 4 GDScript only. If the fix depends on a change listed
in the "Upgrading from Godot 3 to Godot 4" docs, say which one.
Don't rename nodes or touch other files.

Error:
<paste the error>

Script:
<paste the script>

Step 5: Update your version control settings

The docs add: "Godot 3.x and 4.x have entirely different lists of files and folders that should be ignored by your version control system." (checked Oct 2026)

The version control page says the .godot/ folder "stores various project cache data." (checked Oct 2026) For an existing project, you can "select the Project menu at the top of the editor, then choose Version Control > Generate Version Control Metadata." (checked Oct 2026)

Our advice, not a vendor quote: check what that creates against any .gitignore you already have before you commit it.

A short checklist

Our advice, not a vendor quote:

Not affiliated with or endorsed by the Godot Foundation or the Godot Engine project. If this guide and the Godot docs ever disagree, trust the docs.