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
fgvm install 4.5-stable-standard # Exact release triplet

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                       # Launch project using its pinned version

Export project presets:

fgvm export                      # Export every configured preset
fgvm export --output dist        # Export to ./dist/

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 effective Godot executable path

Commands Reference

Run fgvm --help for a command summary or fgvm <command> --help for command-specific syntax.

Note: Commands with queries accept a variable number of words, so options must come before the query. Use fgvm install --default 4.4.1 rather than fgvm install 4.4.1 --default, for example.

Core Commands

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

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. Use --verbose (or -V) to show each download source as it is tried.

See Version Query System for how fuzzy queries and exact triplets are resolved.

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:

• Version selection: Reads .fgvm-version when present, otherwise uses the global default
• Missing version prompts: Offers to install an unavailable pinned release
• 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

By default, Godot runs independently in detached mode and remains open after fgvm or the terminal exits. Use --attached or an auto-attached argument when terminal output is required.

The command reads existing .fgvm-version files for version selection but does not create or modify them. Use fgvm local to manage project pins.

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
• Existing pin: Requires an exact major.minor[.patch]-release-runtime triplet
• Project detection: Uses the same major and minor version and never selects a patch older than project.godot requests
• Configured exports: Installs the complete official export-template package when export_presets.cfg contains a configured preset
• Failure handling: Validates relevant preset metadata before changing the editor or pin; a later template failure leaves the selected editor and .fgvm-version in place for a retry

fgvm export [-o|--output <path>] [-a|--archive] [-j|--json] [--manifest <path>] [<...strings>]

Prepare the matching editor and export templates, import the project once, and export every named preset in export_presets.cfg in declaration order.

Options and output:

• Without --output, each preset uses its configured export_path; a blank path receives an isolated fallback beneath dist/<preset>/
• --output <path> places every preset in an isolated directory beneath that root and replaces those directories after successful exports
• --archive uses Godot's native --export-pack mode to create a data-only ZIP pack rather than a playable release export
• Every successful run writes .fgvm-export.json; use --manifest <path> to change its location
• --json or -j writes the same handoff manifest to standard output while human-readable progress and errors go to standard error

Options must appear before the optional version query, for example fgvm export --archive --manifest artifacts.json 4.6 mono.

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

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 [--with-templates] [<...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.

Use --with-templates to also remove the export templates matching each removed editor. Without it, removing an editor leaves its templates installed.

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 [--force] [-V|--verbose] [<...strings>]

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. Use --force to replace an existing package and --verbose (or -V) to show each download source as it is tried.

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 - Exact version locking with a complete release triplet
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

Short version queries are fuzzy: 4.5, 4.5 stable, and 4.5-stable select the latest stable 4.5 patch. A complete major.minor[.patch]-release-runtime triplet is exact and must match an available release. Numbered prereleases must include their number, so use 4.8-dev4-mono instead of 4.8-dev-mono.

.fgvm-version must contain an exact triplet. Existing pins such as 4.5-stable need either -standard or -mono appended. Running fgvm local with a fuzzy query writes the resolved triplet. Versions detected from project.godot remain compatible within the same major and minor version, but fgvm will not select a patch older than the project requests.

Supported query components include:

• 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 release triplets: 4.5-stable-standard, 4.4.1-stable-mono, 4.8-dev4-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.