The best command-line tool to install and switch between multiple versions of Godot.

Inspired by xcodes and built with ❤️ in Rust.

Special thanks to Blaze for their support of this project. They provide high-performance Linux (AMD64 & ARM64) and Apple Silicon macOS runners for GitHub Actions, greatly reducing our automated build times.

$ gdenv --help
A beautiful terminal tool for managing Godot installations

Usage: gdenv [OPTIONS] <COMMAND>

Commands:
  run     Invoke Godot for the current project
  editor  Open the Godot editor for the current project
  sync    Synchronize Godot addons with the project's configuration file
  godot   Manage Godot versions
  help    Print this message or the help of the given subcommand(s)

Options:
  -p, --project <PROJECT>  Path to a gdenv managed project (defaults to current directory)
      --datadir <DATADIR>  Use a different location for gdenv's data, where downloads and installations are kept (useful for testing)
  -h, --help               Print help
  -V, --version            Print version

$ gdenv godot --help
Manage Godot versions

Usage: gdenv godot [OPTIONS] <COMMAND>

Commands:
  fetch      Update the cache of available Godot versions
  list       List installed and available Godot versions
  install    Download and install a specific version of Godot
  use        Switch to a specific Godot version
  current    Show the currently active Godot version
  uninstall  Uninstall a specific Godot version
  cache      Manage download cache
  help       Print this message or the help of the given subcommand(s)

Options:
  -p, --project <PROJECT>  Path to a gdenv managed project (defaults to current directory)
      --datadir <DATADIR>  Use a different location for gdenv's data, where downloads and installations are kept (useful for testing)
  -h, --help               Print help

# Unix/Linux/macOS
curl -fsSL https://gdenv.bytemeadow.com | sh

# Windows PowerShell
irm https://gdenv.bytemeadow.com | iex

# For the latest unstable version
cargo install --git https://github.com/bytemeadow/gdenv
# For the version released to crates.io
cargo install gdenv

Download pre-built binaries from GitHub Releases

Install a specific version of Godot using commands like:

gdenv install 4.4.1
gdenv install 4.5-beta1
gdenv install 3.6 --dotnet
gdenv install --latest
gdenv install --latest-prerelease

gdenv will download and install the version you asked for so that it's ready to use.

A gdenv.toml file is used to configure various aspects about a Godot project such as the Godot version to launch with, Godot addons to synchronize, and GdExtension files to generate. Gdenv will look for this file in the current directory and all parent directories.

Example gdenv.toml file:

[godot]
version = "4.6.0-stable"
project_dir = "godot"

[gdextension.1.Rust]
cargo_crate_path = "rust"

[addon.godot-bevy]
git = "https://github.com/bytemeadow/godot-bevy"
rev = "v0.10.0"
subdir = "addons/godot-bevy"

For the full list of parameters, see gdenv_schema.toml. Gdenv can output the full list of parameters with gdenv schema for easy CLI reference.

An alternative to gdenv.toml is to use the much simpler .godot-version file. The file contains only a Godot version string. gdenv will use this version for all commands that require a Godot version unless otherwise specified.

Example .godot-version file:

4.4.1-stable

Then run:

gdenv install  # Installs 4.4.1-stable
gdenv use      # Switches to 4.4.1-stable

gdenv can be used directly as a GitHub Action:

- name: Setup Godot
  uses: bytemeadow/gdenv@v0.2.2
  with:
    version: 4.5.1
    gdenv-version: 0.2.2
    use-dotnet: false
    include-templates: false
    cache: true

• version (required): Godot version to install and activate.
• use-dotnet (default: false): install/use .NET Godot builds.
• include-templates (default: false): install export templates for the selected version.
• cache (default: true): cache gdenv data and templates between runs.
• gdenv-version (default: latest): gdenv version to install.
• output godot-bin: absolute path to the resolved Godot executable.

The action adds godot to PATH and sets GODOT, GODOT4, and GODOT4_BIN to godot.

gdenv is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE-APACHE and LICENSE-MIT for details. Opening a pull request is assumed to signal agreement with these licensing terms.