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.
• 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, which can be automatically detected from project.godot or manually customized if needed. Also prompts to install missing versions when opening a project that is using a version that isn't currently installed. Finally, automatically launch your project using the godot command 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: Perfect for remote installations, CI/CD pipelines, WSL, and containerized environments with its single static binary.

Installation

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

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

brew tap patricktcoakley/formulae
brew install fgvm

brew tap patricktcoakley/formulae
brew install fgvm

🔧 Build from Source (All Platforms)

Clone the repository and build with .NET 9 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 -i                # Interactive version picker

Launch Godot:

fgvm godot                 # Launch default version
fgvm godot -i              # Interactive version picker
fgvm godot --args --headless  # Pass arguments to Godot

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>] [--default|-D|--set-default]

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.

fgvm list

List all locally installed Godot versions showing version, type, and runtime.

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 [options]

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
• --attached|-a - Force terminal attachment for output

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 best matching version and updates .fgvm-version
• Smart compatibility: Only installs if no compatible version exists

fgvm search [<...strings>]

Search all available remote Godot versions with filtering.

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

Display the file path that the current Godot symlink points to.

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

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

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.