✨ Features

December 20, 2025 · View on GitHub

Godot Version Manager

A command line tool to download and manage Godot versions per project

download any release of Godot > 3.0 from the command line
define a Godot version for your project and track it with git
seamlessly download and run the correct Godot version accross projects and git commits
set a system's default version of Godot, with desktop shortcut
support for custom builds
autocompletion
interactive prompt
colors 🎉

Download the latest release and extract it.
Install gdvm by running the install script from the extracted directory:

cd gdvm
./install

Note

If you encounter a glibc error follow the install instructions for developers

Run gdvm -h for advanced usage

gdvm download VERSION_NUMBER
gdvm use VERSION

gdvm supports autocompletion of all arguments including all possible versions.

Alternatively you can use the interactive mode:

gdvm download
gdvm use

If you'd like to use a release other than stable, such as rc1 or dev5, you can complete the version with -rc1 or - and use autocompletion:

gdvm download VERSION_NUMBER-RELEASE
gdvm use VERSION

Note

The local version is written to .godotversion in the current working directory. Track it with git ;)

gdvm use --system-default VERSION

or for the interactive mode:

gdvm use --system-default

Both running godot in the terminal or opening Godot's desktop application will point to the new installed version.

gdvm run runs the current working directory's project with project's version if it has been previously defined, otherwise asks to select the version to run.
gdvm run VERSION to run a specific version
gdvm run -v --system to run the system's default and let godot print its output to terminal
gdvm run -- <godot-arguments> to pass any list of arguments to the godot executable

gdvm supports wildcards to handle multiple versions at once. For example to remove all rc releases of versions starting with 4.1:

gdvm remove "4.1x-rcx"

Dependencies are handled by uv, follow these install instructions

git clone https://github.com/gaheldev/godot-version-manager.git
cd godot-version-manager

We use virtualenv to create an environment with controlled python package versions.

uv venv
source venv/bin/activate

Make sure to run source venv/bin/activate before working on the project.
Run deactivate to deactivate the virtualenv.

make install

Warning

this will delete any pre-commit hook you already created

To automatically run tests before commits we use a pre-commit hook:

make hook

Warning

if a hook has been changed by you or someone else, you need to run make hook again

Tests are located in the tests/ folder of the project. All test files should be named 'test_*.py' or '*_test.py'.

Run make tests in the project's root directory to run all tests.

Releases are automatically built on github when a tag v*.*.* is pushed by one of the commands:

make patch-release
make minor-release
make major-release

For a detailed profiling, use cProfile on main.py from the root directory, for example:

python -m cProfile main.py list > profiling.txt

For a basic profiling you can use the time utility:

time gdvm list