gdvm
gdvm 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
.gdvm-version
file in the project directory, which can be automatically detected fromproject.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 thegodot
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
Windows Installation
📦 Scoop (Recommended)
Install using Scoop:
scoop bucket add patricktcoakley https://github.com/patricktcoakley/scoop-bucket
scoop install patricktcoakley/gdvm
⚡ gdvmup (Alternative)
Experimental one-line PowerShell installer:
irm https://raw.githubusercontent.com/patricktcoakley/gdvm/main/installer.ps1 | iex
💾 Manual Binary
macOS Installation
🍺 Homebrew (Recommended)
Install using Homebrew:
brew tap patricktcoakley/formulae
brew install gdvm
Linux Installation
🍺 Homebrew (Recommended)
Install using Homebrew on Linux:
brew tap patricktcoakley/formulae
brew install gdvm
💾 Manual Binary (Alternative)
🔧 Build from Source (All Platforms)
Clone the repository and build with .NET 9 SDK:
git clone https://github.com/patricktcoakley/gdvm.git
cd gdvm
dotnet build -c Release
Quick Usage
Install Godot versions:
gdvm install latest # Latest stable release
gdvm install latest mono # Latest .NET stable release
gdvm install 4 mono # Latest 4.x with .NET support
gdvm install 3.3 rc # Latest 3.3 release candidate
gdvm install 4.4.1 # Specific version
Set default version:
gdvm set 4.3-stable-mono # Set specific version as default
gdvm set -i # Interactive version picker
Launch Godot:
gdvm godot # Launch default version
gdvm godot -i # Interactive version picker
gdvm godot --args --headless # Pass arguments to Godot
Project-specific versions:
gdvm local # Detect and set version for current project
gdvm local 4.3 mono # Set specific version for project
gdvm godot # Auto-detects project version
List and manage versions:
gdvm list # Show installed versions
gdvm search 4 # Search available versions
gdvm search 4.2 rc # Search specific release candidates
gdvm remove 3.6-stable-mono # Remove installed version
gdvm which # Show current default version location
Commands Reference
Core Commands
gdvm install [--query|-q <...strings>]
Install Godot versions with powerful query system. If no arguments are supplied, prompts interactively.
Query Examples:
gdvm install latest
- Latest stable releasegdvm install latest mono
- Latest .NET stable releasegdvm install 4 mono
- Latest stable 4.x .NET releasegdvm install 3.3 rc
- Latest 3.3 release candidategdvm install 4.4.1-stable-mono
- Exact version match
The last installed version automatically becomes the default.
gdvm list
List all locally installed Godot versions showing version, type, and runtime.
gdvm set [--interactive|-i] [<...strings>]
Set the default Godot version. Prompts interactively if no arguments supplied.
Options:
--interactive|-i
- Select from already installed versions- Query support for partial matches (e.g.,
4
,4.4
,stable
,mono
)
gdvm godot [options]
Launch Godot with intelligent version detection and project awareness.
Key Features:
- Auto-detection: Reads
.gdvm-version
orproject.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
gdvm local [--interactive|-i] [<...strings>]
Manage project-specific versions via .gdvm-version
files.
Behavior:
- No arguments: Detects version from
project.godot
or existing.gdvm-version
- With query: Finds best matching version and updates
.gdvm-version
- Smart compatibility: Only installs if no compatible version exists
--interactive|-i
- Select from installed versions
gdvm search [<...strings>]
Search all available remote Godot versions with filtering.
Query Examples:
gdvm search 4
- All 4.x releasesgdvm search 4.2-rc
- Only 4.2 RC releasesgdvm search 4.2 rc
- All 4.2.x RC releases (including 4.2.2-rc3)
gdvm 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:
gdvm remove 4
shows all 4.x versions
Removing the current default version will unset it.
gdvm which
Display the file path that the current Godot symlink points to.
gdvm logs [--level|-l <string>] [--message|-m <string>]
View application logs with optional filtering by level or message content.
Installation Paths
Storage locations:
- macOS/Linux:
~/gdvm/
- Windows:
C:\Users\USERNAME\gdvm\
Folder structure: VERSION-TYPE-RUNTIME
(e.g., 4.3-stable-mono
)
Symlinks: Created in bin/
folder for easy access via gdvm godot
Project Integration
GDVM integrates seamlessly with Godot projects through:
.gdvm-version
files - Explicit version lockingproject.godot
detection - Automatic version detection from project files- Missing version handling - Prompts to install required versions
- Direct launching -
gdvm godot
opens projects with correct version
Version Query System
GDVM 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
Learn More
For detailed documentation, advanced features, and troubleshooting, visit the full README on GitHub.