> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/gum-tool/upgrading/upgrading-file-gumx-version.md).

# Upgrading File (GUMX) Version

## Introduction

Gum project files include a `Version` tag which is used by the Gum tool and Gum runtimes to determine how to handle the file.

Unless otherwise stated below, these version upgrades are optional - you can continue to use old versions.

## Upgrading Versions

{% hint style="danger" %}
Upgrading your Gum version can make changes to your project which cannot be undone. Before performing any upgrades, be sure to back up your project, or start with a clean commit in Git.
{% endhint %}

To upgrade to a new version:

1. If open, close the Gum tool.
2. Open your Gum project file (.gumx) in a text editor
3. Search for the \<Version> XML tag. For example your file may have

   ```xml
   <Version>1</Version>
   ```
4. Change the version number to the desired version.
5. Save the .gumx file
6. Open the Gum tool

Gum should detect the new version and if any changes are necessary to your project, Gum will perform them.

If the change modifies how the file is saved, you may need to use the **File** -> **Save All** command to forcefully save all files to disk.

## Version 1

The initial file version, which was used until February 2026.

## Version 2

**Required Gum Tool Version**: February 2026

This version uses XML Attributes to greatly reduce the size of XML files and to make manual editing and diffing of files easier.

✅No manual changes are needed to your project beyond changing the version number.

❗Be sure that your entire team is using the new version of the Gum (February 2026 or later) before making any upgrades, and once the upgrade has been made, make sure that no one on your team is still making Gum changes on V1. This can cause a "hybrid" file which is partially V2 and partially V1, which can break a project.

After changing the version number:

1. Open the Gum project in the Gum tool
2. Select File->Save All to save all files to disk using the new attribute format.

You should notice significant reduction in file size and number of lines. The following files will be affected by this change:

* Screen files
* Component files
* StandardElementSave files
* Main Gum project file

Before:

<figure><img src="/files/RrAh3u3quC7bb2jmqane" alt=""><figcaption></figcaption></figure>

After:

<figure><img src="/files/ybmdFRYJcgXhaMLnYZZI" alt=""><figcaption></figcaption></figure>

Note that the file savings vary by project type and by content type.

The savings are both in file size, but also in line number which makes comparing files in diffs much easier than before. Here are some typical savings in line count. These were taken from the Cranky Chibi Cthulhu game (<https://store.steampowered.com/app/2631990/Cranky_Chibi_Cthulhu/>)

* GumProject .gumx file: 620 -> 180 lines
* PauseMenu Component: 513 -> 248 lines
* GameScreenGum Screen: 798 -> 381 lines
* SplashScreenGum Screen: 63 -> 37 lines
* PlayerHud Component: 2646 -> 1309 lines
* Circle Standard Element File: 165 -> 72 lines

## Version 3

**Required Gum Tool Version**: 2026 May (or later)

This version unlocks the expanded **Circle** and **Rectangle** shape variables — fill, gradient, drop shadow, stroke-and-fill, and antialiasing — along with the Circle `Radius` -> `Width`/`Height` change. The tool only shows these new variable categories for projects at version 3 or later, so a project still at version 2 keeps the new shape variables hidden even on a tool build that supports them.

✅No manual changes are needed to your project beyond changing the version number.

Unlike Version 2, which is a real XML-format change requiring a **File** -> **Save All** to rewrite every file, Version 3 uses the **same XML format** as Version 2. The version bump exists only to unlock the new variable surface and to make older tool builds refuse the file rather than silently dropping the new variables on the next save. There is **no format conversion or Save All step** — you only change the `<Version>` number.

❗Be sure that your entire team is using the new version of Gum (2026 May or later) before making this upgrade. As with Version 2, mixing tool versions across a team can produce a "hybrid" file which can break a project.

{% hint style="info" %}
New projects created with the 2026 May tool (or later) are stamped Version 3 automatically. Only projects created before this release need the manual bump.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flatredball.com/gum/gum-tool/upgrading/upgrading-file-gumx-version.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.