GodotEnv: version managers and addon management for the Godot engine

What the tool does, in the author's own list

GodotEnv is a command-line tool that makes it easy to switch between Godot versions and manage addons in your projects. The README opens with a checklist of what it can do, and that list is the clearest summary of the design.

It can download, extract and install Godot 3.0 and 4.0 or later versions from the command line on Windows, macOS and Linux, and the README compares it to tools like NVM, FVM and asdf. It switches the active version of Godot by updating a symlink. It automatically sets up a user GODOT environment variable that always points to the active version. It installs addons in a Godot project from local paths, remote git repositories or symlinks, using an addons.json file, with the stated benefit of no more fighting with git submodules, and you just run godotenv addons install whenever that file changes. It can automatically create and configure a.gitignore, an addons.json and an addons/.editorconfig in your project to make addon management easier. And addons can declare dependencies on other addons using a flat dependency graph.

That last item is the one that shows the most thought. Addons that depend on other addons are common in the Godot ecosystem, and the usual solutions, git submodules, are painful enough that a lot of projects avoid addon dependencies entirely. A flat dependency graph is the simplification: each addon declares what it needs and the tool resolves the order.

The tool is a.NET command line tool, published on NuGet as Chickensoft.GodotEnv, MIT licensed, and the last push was on 2026-10-21 with the newest release v2.17.0 from 2026-07-13.

The language choice is not incidental. The tool is written in C#, and it targets the.NET build of Godot by default, so a team already using Godot with C# has a single runtime to deal with.

Installing the tool, and the NuGet source problem it runs into

Installation is a global dotnet tool install:

dotnet tool install --global Chickensoft.GodotEnv

The README then spends more space on failure modes than on anything else, and the first one is specific: if you encounter the error No NuGet sources are defined or enabled, add a NuGet source or enable one and try installing GodotEnv again.

The diagnostic is to list the current sources and see which are enabled:

dotnet nuget list source

If no sources are listed, you add one:

dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

Otherwise you make sure an existing one is enabled:

dotnet nuget enable source <NAME>

The second prerequisite is less obvious and worth stating plainly. GodotEnv uses the local git installation and other processes available from the shell, so you have to have git installed and your local shell environment configured correctly, with a link to the SSH and GitHub setup instructions.

That matters because the addon system clones repositories. A tool that shells out to git inherits git's credential configuration, SSH agent setup and proxy behaviour, which is both a strength and a source of environment-specific failures.

The Windows note covers the platform's particularities. Certain operations may require administrator privileges, such as managing symlinks or editing certain files. GodotEnv should prompt you for approval in those cases, and certain operations will cause a command line window to pop open for a moment before disappearing, which the README says is normal. In some cases, enabling Developer Mode may be required for GodotEnv to correctly manage symlinks.

Installing a Godot version and what happens behind the command

Installing a version takes the version as an argument, and a non-stable version is installed the same way:

godotenv godot install 4.0.1
# or a non-stable version:
godotenv godot install 4.1.1-rc.1

Versions should match the format of the versions shown on the GodotSharp nuget package, and downloads are made from GitHub Release Builds.

The .NET question comes up immediately. By default, GodotEnv installs .NET-enabled versions of Godot. The non-.NET build is available with a flag, and the README is unapologetic about the preference:

godotenv godot install 4.0.1 --no-dotnet

That default only makes sense in context. The tool is written in C# and its author is the Chickensoft games group, whose Godot work is C#-based, so the .NET build is the sensible default for the audience.

The install performs four steps. It downloads the Godot installation zip archive, if it has not been downloaded already. It extracts that archive. It activates the newly installed version by updating the symlink. And it makes sure the user GODOT environment variable points to the active Godot version symlink.

The result is that running Godot means typing $GODOT in a shell, and the README notes that the Godot executable should also be in your path after restarting your shell. On Windows the first install may require logging out and back in for the $GODOT variable to be picked up by the shell and other applications.

So the model is a version manager in the NVM sense. One active version at a time, selected by a symlink, with an environment variable pointing at that symlink rather than at a specific build directory. Switching versions later is a symlink update, not a reinstall.

Listing, switching, and inferring the version from the project

The listing command shows what you have installed:

godotenv godot list

and the output is a plain list, with a marker for the .NET variants:

4.0.1
4.0.1 *dotnet
4.1.1-rc.1
4.1.1-rc.1 *dotnet

Remote versions are available through the -r option:

godotenv godot list -r

Switching is the same operation as installing, minus the download, since the symlink just moves:

# uses dotnet version
godotenv godot use 4.0.1

# uses non-dotnet version
godotenv godot use 4.0.1 --no-dotnet

By default the use command only looks for the .NET-enabled version, which is why the --no-dotnet variant exists for the other case.

The feature that is genuinely useful on a team is version inference. You can run the install or use commands without a version argument and GodotEnv will work out the right version from files in your directory tree:

# installs version inferred from project files
godotenv godot install

# uses version inferred from project files
godotenv godot use

It walks up the directory tree and looks at three things, in order of precedence. A global.json specifying a Godot.NET.Sdk value in msbuild-sdks. A csproj file specifying a versioned Godot.NET.Sdk as its Project SDK. And a .godotrc file with a Godot version string as its first line.

The precedence rules are where this gets subtle, and the README spells them out. A global.json at any directory level above the working directory takes precedence over all csproj files, even those closer to the working directory, and similarly for any csproj file. That ordering is unusual enough to be worth reading rather than guessing at, and it is the kind of detail that saves an afternoon when two projects in the same tree need different engine versions.

Addon management, and the boundary the tool draws

The addon system is the second half of the tool, and it is the part that changes how a project is organised.

Addons are declared in an addons.json file at the project root, and each entry can point at a local path, a remote git repository or a symlink. The install command reads that file and puts the addons in place, and the workflow the README describes is simply to run godotenv addons install whenever your addons.json file changes.

The benefit over git submodules is stated directly: no more fighting with git submodules. That is a real and well-known problem in Godot projects. Submodules are painful to clone correctly, painful to update across a team, and easy to leave in a broken state in a fresh checkout. A declarative JSON file with a tool that reconciles the working directory is a much simpler contract.

The dependency support is worth understanding in terms of what it does not do. Addons declare dependencies on other addons using a flat dependency graph, A flat graph means no version constraints between addons and no nested dependency trees, which makes resolution easy and predictable at the cost of expressiveness.

The project scaffolding is part of the deal too. GodotEnv can automatically create and configure a.gitignore, an addons.json and an addons/.editorconfig in your project, which means a new contributor can clone the repository and get a working addon set with one command rather than by following a setup document.

There is one documented boundary for CI. Using GodotEnv to install Godot works best for local development, and for installing Godot directly on a GitHub Actions runner for CI/CD the project points to Chickensoft's setup-godot action instead, which caches Godot installations between runs, installs the Godot export templates, and works on Windows, macOS and Ubuntu runners. The distinction is caching, and export templates, which GodotEnv does not handle.

The repository layout reflects a normal.NET solution: GodotEnv.sln, a GodotEnv directory for the tool, GodotEnv.Tests for the tests, a TestPackage directory, plus the usual.editorconfig, cspell.json, renovate.json, CONTRIBUTING.md and doc_assets. The global.json at the root is notable, since it is also one of the files the version inference looks for.

Editorial conclusion

Adopt GodotEnv if you work across more than one Godot version or share a project with addons, because it removes the manual download, the PATH juggling and the submodule mess in one tool. Do not adopt it for CI runners, where the project itself points to the Chickensoft setup-godot action instead, since that action caches installations between runs and installs the export templates. Before you start, make sure git is installed and your shell is configured for GitHub over SSH, and on Windows expect to enable Developer Mode and possibly log out and back in so the GODOT variable is picked up.

Frequently asked questions

Official sources

1. chickensoft-games/GodotEnv on GitHub
2. License: MIT
3. Project website
4. README
5. Releases