If you upgraded a Godot project from 4.3 to 4.4 and suddenly saw a wave of new .uid files next to every .gd and .gdshader, you were not alone. Every GitHub thread I found from early 2025 had someone asking whether to delete them, gitignore them, or commit them.
The answer is: commit them. They are not noise. They fix a real problem Godot has had since day one, and understanding them is the difference between a clean refactor and a broken scene tree the next morning.
The problem the .uid files solve
Before 4.4, Godot referenced every resource by its file path. If you moved res://scripts/player.gd to res://entities/player/player.gd without doing it through the editor, every scene that referenced that script would break. The typical workflow for a larger team looked like:
- Refactor the folder structure outside the editor (in VS Code or the terminal)
- Reopen Godot
- Watch half your scenes fail to load
- Manually re-link every broken reference in the inspector
Godot already used UIDs for scenes and most imported resources. But scripts and shaders were excluded because they are plain text files with no place to store engine metadata. You moved player.gd and Godot had no way to know it was still the same script.
The 4.4 release solves that with sidecar files. player.gd now ships with player.gd.uid alongside it. The .uid file contains a single line: a UID like uid://c82j4l3r4k4n2. Every scene that references that script stores the UID, not the path. Move the file to another folder, and Godot finds it through the UID.
What file types got .uid files
The Godot blog post is explicit about which types are affected:
| Source file | Sidecar file |
|---|---|
.gd (GDScript) |
.gd.uid |
.cs (C#) |
.cs.uid |
.gdshader (shader) |
.gdshader.uid |
.gdshaderinc |
.gdshaderinc.uid |
Scenes (.tscn) and most imported resources already had UIDs stored in their own headers since earlier versions, so they did not need sidecars. This change is specifically for the plain-text formats that previously had no UID hook.
The .gitignore mistake
The single biggest footgun with the new system is treating .uid files like build artifacts and adding them to .gitignore. I have seen this in multiple public Godot repos since the 4.4 release. If you gitignore .uid, every clone of your repo generates fresh UIDs, and every scene that references your scripts points at UIDs that exist only on the original author's machine. The project opens, the scripts technically load, but the scene-to-script links are now broken for every collaborator.
The correct answer, per the Godot team: commit the .uid files to version control. They are part of your project state, not generated output.
What this means for external refactoring
The part I like most is that moving files outside the editor is now officially supported. Before 4.4, the unwritten rule was "always do refactors inside Godot." Now you can:
- Close Godot
- Run
git mvormvon any script or shader, together with its.uidsidecar - Reopen Godot
The editor looks up the UID, finds the file in its new location, and updates the path in any referencing scene when you save. Nothing breaks. This is the kind of affordance that only matters when your project is large enough that "refactor inside the editor" becomes tedious, but at that point it matters a lot.
One gotcha: the UID cache can lag
There is a known bug where renaming a scene file externally does not immediately update the UID cache, which can cause temporary stale references. The fix is to reopen the project so Godot rescans the filesystem. The bug is open as of writing and affects the 4.4 line; the 4.6 release did not mark it as fixed. If you hit it, reopening the project clears it.
What this has to do with AI coding tools
Every AI assistant trained on pre-4.4 Godot does not know what a .uid file is. Ask ChatGPT or a generic coding assistant to refactor your Godot project's folder structure, and it will happily suggest moving scripts without moving their .uid sidecars. You run the suggested commands, reopen the editor, and watch your scenes break in the exact way the UID system was designed to prevent.
Tools that run natively inside the Godot editor (there are a handful now, Ziva being one of them) have a structural advantage here: they can read the current UID index directly, know which sidecar belongs to which source file, and keep them together on any file operation. The generic chatbot approach cannot do this. It can only suggest; it cannot see.
If you are evaluating AI tooling for Godot work, this is the kind of thing to test. Ask your candidate tool to move player.gd from one folder to another and see whether it touches the .uid file. If not, expect broken scenes.
Practical migration checklist
If you are upgrading a Godot 4.3 project to 4.4 or later today, three things make the transition painless:
- Open the project in 4.4 and re-save every scene. The editor regenerates UID references in each scene file, which is what makes the sidecars useful. This is a one-time cleanup.
-
Remove any
*.uidentry from your.gitignoreif it exists. Commit the files. They are ~30 bytes each and they are part of the project. -
When moving files externally, always move the
.uidalongside.git mv player.gd entities/player/player.gd && git mv player.gd.uid entities/player/player.gd.uidis the pattern.
The UID system is one of the Godot 4.x changes that feels invisible until it saves you an afternoon of re-linking references. Treat the sidecar files the way you treat package-lock.json or Cargo.lock: commit them and forget about them.
