fgvm

fgvm is a friendly Godot version manager that lets you install and manage multiple versions of Godot with ease. It uses a hybrid CLI/TUI design with flexible query support, allowing you to find versions using keywords like latest, 4 mono, or 3.3 rc4. It works on Windows, macOS, and Linux with support for both standard and .NET builds.

Features

• Version Management: Easily manage multiple Godot installations side-by-side, allowing you to try out the latest versions or keep older versions for compatibility testing, including Godot 1.0 to the latest development builds, including both standard and .NET builds.
• Export Template Management: Install, list, and remove Godot export templates for locally installed Godot versions.
• Hybrid CLI/TUI Interface: Simple command-line interface with interactive TUI prompts for easy navigation and selection when you don't specify arguments.
• Flexible Query System: Powerful query system for finding and installing versions using keywords like latest, 4 mono, 3.3 rc, etc.
• Project Aware: Lock a project to a specific Godot version using a .fgvm-version file in the project directory. fgvm local can automatically detect a compatible version from project.godot or let you manually choose one, and will prompt to install missing versions when needed. fgvm godot uses .fgvm-version when present, otherwise falls back to the global default, and can launch the current project directly from the terminal.
• Smart Argument Handling: Detection of arguments passed to Godot that contextually switch to an attached mode when necessary to display terminal output.
• CI-Ready: Suitable for remote installations, CI/CD pipelines, WSL, and containerized environments with its single self-contained native executable.

Installation

Package managers are the recommended install path because they make upgrades straightforward. If you prefer not to use a package manager, use the install script for your platform; run the same script again later to upgrade. For manual downloads, custom install paths, and checksum commands, see the README installation guide.

scoop bucket add patricktcoakley https://github.com/patricktcoakley/scoop-bucket
scoop install patricktcoakley/fgvm

mise use -g github:patricktcoakley/fgvm
fgvm --version

irm https://raw.githubusercontent.com/patricktcoakley/fgvm/main/installer.ps1 | iex

brew tap patricktcoakley/formulae
brew trust patricktcoakley/formulae
brew install fgvm

mise use -g github:patricktcoakley/fgvm
fgvm --version

curl -fsSL https://raw.githubusercontent.com/patricktcoakley/fgvm/main/installer.sh | sh

brew tap patricktcoakley/formulae
brew trust patricktcoakley/formulae
brew install fgvm

mise use -g github:patricktcoakley/fgvm
fgvm --version

curl -fsSL https://raw.githubusercontent.com/patricktcoakley/fgvm/main/installer.sh | sh

🔧 Build from Source (All Platforms)

Clone the repository and build with .NET 10 SDK:

git clone https://github.com/patricktcoakley/fgvm.git
cd fgvm
dotnet build -c Release

📋 View all releases

Quick Usage

Install Godot versions:

fgvm install latest        # Latest stable release
fgvm install latest mono  # Latest .NET stable release
fgvm install 4 mono       # Latest 4.x with .NET support
fgvm install 3.3 rc       # Latest 3.3 release candidate
fgvm install 4.4.1        # Specific version

Set default version:

fgvm set 4.3-stable-mono   # Set specific version as default
fgvm set                   # Interactive version picker

Launch Godot:

fgvm godot                 # Launch effective version
fgvm godot -i              # Interactive version picker
fgvm godot --args "--headless"  # Pass arguments to Godot
fgvm godot --args "--version"   # Print Godot version

Project-specific versions:

fgvm local                 # Detect and set version for current project
fgvm local 4.3 mono        # Set specific version for project
fgvm godot                 # Auto-detects project version

List and manage versions:

fgvm list                  # Show installed versions
fgvm search 4              # Search available versions
fgvm search 4.2 rc         # Search specific release candidates
fgvm remove 3.6-stable-mono # Remove installed version
fgvm which                 # Show current default version location

Commands Reference

Core Commands

fgvm install [<...strings>] [-D|--default] [--with-templates]

Install Godot versions with powerful query system. If no arguments are supplied, prompts interactively.

Query Examples:

• fgvm install latest - Latest stable release
• fgvm install latest mono - Latest .NET stable release
• fgvm install 4 mono - Latest stable 4.x .NET release
• fgvm install 3.3 rc - Latest 3.3 release candidate
• fgvm install 4.4.1-stable-mono - Exact version match

The first installed version automatically becomes the default. Use --default (or -D) to explicitly set the installed version as the default regardless of whether other versions are already installed. Use --with-templates to install the matching official export templates after the editor installation succeeds.

fgvm list [--json]

List all locally installed Godot versions showing version, type, runtime, and launch metadata. Use --json to output JSON.

fgvm set [<...strings>]

Set the default Godot version. Prompts interactively if no arguments supplied.

Supports query filtering for partial matches (e.g., 4, 4.4, stable, mono) or exact version matches (e.g., 4.4.1-stable-mono).

fgvm godot [-i|--interactive] [-a|--attached] [-P|--project] [--query <string>] [--args <string>]

Launch Godot with intelligent version detection and project awareness.

Key Features:

• Auto-detection: Reads .fgvm-version or project.godot files
• Missing version prompts: Offers to install required versions automatically
• Direct project launching: Opens projects directly from terminal (Godot 4.0+)

Options:

• --interactive|-i - Choose from installed versions
• --args "<arguments>" - Pass arguments to Godot executable
  • Use a space after --args, such as fgvm godot --args "--version"
  • Do not use --args="..."; that form is rejected by the CLI parser
• --attached|-a - Force terminal attachment for output
• --project|-P - Add the detected project path to explicit Godot arguments
• --query <string> - Launch a specific installed version, such as --query "4.6 mono"

Auto-attached mode for arguments like --version, --help, --headless

fgvm local [<...strings>]

Manage project-specific versions via .fgvm-version files.

Behavior:

• No arguments: Detects version from project.godot or existing .fgvm-version
• With query: Finds the best matching version and updates .fgvm-version
• Smart compatibility: Only installs if no compatible version exists

fgvm search [<...strings>] [-j|--json] [-F|--no-cache]

Search all available remote Godot versions with filtering.

Use --json or -j to output JSON. Use --no-cache or -F to force a remote refresh instead of using the local release cache.

Query Examples:

• fgvm search 4 - All 4.x releases
• fgvm search 4.2-rc - Only 4.2 RC releases
• fgvm search 4.2 rc - All 4.2.x RC releases (including 4.2.2-rc3)

fgvm remove [<...strings>]

Remove installed Godot versions with smart selection.

Behavior:

• No arguments: Interactive multi-select deletion
• Single match: Direct deletion
• Multiple matches: Prompts for selection
• Query filtering: fgvm remove 4 shows all 4.x versions

Removing the current default version will unset it.

fgvm which [<...strings>]

Display the executable path for the effective Godot installation in the current directory: .fgvm-version first, then the global default. If query arguments are supplied, it resolves them against installed versions instead.

fgvm logs [--json] [-l|--level <string>] [-m|--message <string>]

View application logs with optional filtering by level or message content.

Export Template Commands

fgvm template install [<...strings>] [--force]

Install the official export template package for an installed Godot version. With no query, fgvm prompts from local Godot installations. With a query, it resolves against local Godot installations only, such as fgvm template install 4.4.1 or fgvm template install 4.4.1 mono.

fgvm template list [-j|--json]

List installed export template directories.

fgvm template remove [<...strings>]

Remove installed export template directories. With no query, fgvm prompts from installed export templates. With a query, it removes the exact match directly or prompts when multiple installed templates match.

Installation Paths

Storage locations:

• macOS/Linux: ~/fgvm/
• Windows: C:\Users\USERNAME\fgvm\

Folder structure: VERSION-TYPE-RUNTIME (e.g., 4.3-stable-mono)

Symlinks: Created in bin/ folder for easy access via fgvm godot

Project Integration

FGVM integrates seamlessly with Godot projects through:

1. .fgvm-version files - Explicit version locking
2. project.godot detection - Automatic version detection from project files
3. Missing version handling - Prompts to install required versions
4. Direct launching - fgvm godot opens projects with correct version

Version Query System

FGVM supports flexible version queries, including:

• Version numbers: 4, 4.3, 4.4.1
• Release types: stable, rc, dev, alpha, beta
• Runtimes: mono, standard
• Combined: 4 mono, latest stable, 3.3 rc
• Exact matches: 4.4.1-stable-mono

Migrating from gdvm

If you were using this project in the past then you'll know it used to be called gdvm. Prior to this project's creation and after, there have been several other projects with similar goals using the same name.

In an effort to differentiate this project I decided to change the name to stand out, and am also using it as an opportunity to implement some breaking changes due to some recent updates in the libraries I am using to write this tool.

What this means for you

• gdvm and fgvm are mostly the same workflow but there were minor changes to the commands that are breaking, so consult the updated documentation if you get stuck
• If you are using a package manager (the recommend way to install), you will have to remove the gdvm package and install fgvm
  • Homebrew users: brew update && brew uninstall gdvm && brew install fgvm
  • Scoop users: scoop update && scoop uninstall gdvm && scoop install fgvm
• If you want to keep your current installations, you can copy the existing gdvm directory to fgvm, which will preserve everything. Here are some one-liners that copy them over and delete the gdvm folder:
  • macOS & Linux users: mkdir -p ~/fgvm && cp -r ~/gdvm/* ~/fgvm/ && rm -rf ~/gdvm
  • Windows users: mkdir -Force $env:USERPROFILE\fgvm ; cp -r $env:USERPROFILE\gdvm\* $env:USERPROFILE\fgvm\ ; rm -r -Force $env:USERPROFILE\gdvm
• gdvmup is now called fgvmup. If you were using the old gdvmup installer, run gdvmup uninstall first, which removes everything, then follow the installation instructions above. Be sure to copy over your existing installations using the above commands if you want to keep them.

Learn More

For detailed documentation, advanced features, and troubleshooting, visit the full README on GitHub.