Making Releases - mapeditor/tiled Wiki

Preparing for a new release

For any release

  • Bump the version number in tiled.qbs, appveyor.yml, docs/ and org.mapeditor.Tiled.appdata.xml
  • Update the and org.mapeditor.Tiled.appdata.xml files with the main changes since the last release

For new feature releases

  • Make sure copyright year in About Dialog is up-to-date
  • Update the translation files (by running dist/ from the root folder)
  • Announce the string freeze to the translators

Making a macOS Release

The process of making a macOS release is entirely automated on GitHub Actions. It is triggered on every push, and automatically uploaded to a new release when a tag is pushed. The following steps are required for manual creation of an installer:

First, make sure you can compile Tiled. You can rely on brew for installing both qt and qbs, after which you do a one-time set up of Qbs:

qbs setup-toolchains --detect
qbs setup-qt /usr/local/opt/qt/bin/qmake qt-brew
qbs config profiles.qt-brew.baseProfile xcode-macosx-x86_64
qbs config defaultProfile qt-brew

Alternatively, you can install any other version of Qt. For Tiled releases I currently use Qt 5.15 LTS, which ensures that Tiled can run on macOS 10.13+.

Open the Terminal, and cd into the base folder of your Tiled checkout.

Run qbs to build Tiled:

qbs install --install-root install config:release

If it builds, you should have a in the install folder. You should run macdeployqt on it to copy the relevant Qt libs and plugins into it and apply the fixup-install-names.rb script to address remaining library loading issues. Then open it and make sure it works properly:

/usr/local/opt/qt/bin/macdeployqt install/
cd install
ruby ../dist/macos/fixup-install-names.rb

Code Signing, Notarization and Stapling

The following steps are automated as part of the GitHub Actions workflow as well.

codesign --deep --force --verify --verbose --sign "<your_developer_ID>" --options runtime

After signing, the is zipped up and submitted for notarization:

ditto -c -k --sequesterRsrc --keepParent Tiled-$
xcrun altool -type osx --notarize-app --primary-bundle-id "org.mapeditor.Tiled" --username "<developer_email>" --password "<app_password>" --file Tiled-$

If the notarization was successful, the app can be stapled:

xcrun stapler staple -v

Now we can zip up the app again for distribution!

Making a Windows Release

The process of making a Windows release is entirely automated on AppVeyor. It is triggered when a tag is pushed. The following steps are required for manual creation of an installer:

  • Install Qt. Releases can be made based on either MinGW 8.1 (32-bit or 64-bit) or Visual Studio 2013 (32-bit or 64-bit).
  • Install the WiX toolset.
  • Set either the TILED_SNAPSHOT or TILED_RELEASE environment variable to true.
  • Build Tiled using Qbs (tiled.qbs), with the property projects.Tiled.windowsInstaller:true to enable building of the installer (when building from Qt Creator, put this in the Properties field in the Qbs build step).

If the build succeeds, you should find a tiled-...-winXX.msi file in the build directory.

Other packages to update:

Making a Linux Release

Tiled is being packaged by others for various distributions. In addition, we are releasing an AppImage on GitHub and, as well as maintaining a snap and a Flatpak package, which covers most Linux systems.

The Tiled AppImage is built on GitHub Actions and uploaded to GitHub releases. You can find the commands in .github/workflows/packages.yml file in the repository.

Arch Linux

Remember to flag the Arch Linux package as Out-of-Date.


Tiled is available as a snap on A snap is built automatically for each new commit at and published to the "edge" channel. Tagged releases are built for 64-bit Linux on GitHub Actions and published to the "candidate" channel.

Once the release has been built, promote it to the appropriate channel on Or on the command-line as follows:

snapcraft release tiled <revision> beta,candidate,stable


Update download link and sha256 at

Publishing the release on

While snapshot builds are pushed to automatically, releases are done manually as follows:

mkdir windows-64bit
mkdir windows-32bit
mkdir winxp-32bit
mkdir linux-64bit

mv Tiled-$TILED_VERSION-win64.msi windows-64bit
mv Tiled-$TILED_VERSION-win32.msi windows-32bit
mv Tiled-$TILED_VERSION-winxp.msi winxp-32bit
mv Tiled-$TILED_VERSION-x86_64.AppImage linux-64bit

butler push --userversion=$TILED_VERSION windows-64bit thorbjorn/tiled:windows-64bit
butler push --userversion=$TILED_VERSION windows-32bit thorbjorn/tiled:windows-32bit
butler push --userversion=$TILED_VERSION winxp-32bit thorbjorn/tiled:winxp-32bit
butler push --userversion=$TILED_VERSION Tiled-$ thorbjorn/tiled:macos
butler push --userversion=$TILED_VERSION linux-64bit thorbjorn/tiled:linux-64bit

Notifying Existing Installs

Tiled checks for new versions. If the checked version is more recent that the installed version, a notification about the new version appears in the status bar.

The versions.json file can be edited on the gh-pages branch.

⚠️ ** Fallback** ⚠️