Installation & update 

The installation and update procedures have changed in XMapTools 4.5. XMapTools is now distributed via shell scripts for macOS and Windows, which automate the processes of installation, updating, downloading, extraction and configuration.

Binaries for Apple Silicon M Macs now require MATLAB Runtime 25.1, which is installed automatically by the XMapTools installer. Older Runtime versions (e.g. v99 or v912) are no longer required and can be safely deleted after upgrading.

Binaries for Windows and Intel-based Macs require MATLAB Runtime v99 as for the previous versions of XMapTools 4.

Before installing, ensure that your system meets the requirements.

Refer to the new XMapTools 4.5 Doc for more detailed steps.

Quick way:

MacOS: run this code in a terminal (password required):

Windows: run this code in a Powershell (with administrator rights):

Detailed installation and update procedures are provided below. 

XMapTools 4.5

Please refer to the release notes for more information about this release.

Compatibility

Note: The macOS version is not compatible with Intel processors, and the macOS Intel version is not stable with Apple Silicon processors. The installer auto-detects your architecture.

MacOS

Initial MacOS XMapTools + runtime  installation

The first installation of XMapTools 4.5 and the corresponding MATLAB Runtime can be performed by running this in your terminal:

MacOS version of XMapTools compatible with Apple Silicon processors (M):

The xmaptools.ch is official and used to distribute the compiled version of XMapTools. If you are using XMapTools behind a firewall that blocks access to these, you may have trouble downloading and installing the program. If this is the case, please ask your system admin to add this domain to the firewall allow list. Traffic can be limited to HTTPS.

What happens during installation:

1. Any previous XMapTools installation in /Applications/XMapTools is removed (you may be prompted for your administrator password).
2. The installer archive is downloaded and extracted to a temporary directory.
3. macOS Gatekeeper quarantine flags are cleared so the app can launch.
   The graphical installer opens — follow the steps below to complete the setup.
4. A terminal command ‘XMapTools’ is created so you can launch the app from any terminal window.

Graphical installer steps (macOS):

1. Enter your password to allow the MATLAB Runtime Installer to make changes.
2. Press Next.
3. Leave the default installation folder /Applications/XMapTools to allow automatic updates in the future and press Next.
4. Leave the default installation folder for the Runtime /Applications/MATLAB/MATLAB_Runtime and press Next.
5. Click Begin Install to install XMapTools and download the Runtime (2–3 GB).
6. Press Close when the installation is complete.
7. You can now start XMapTools using XMapTools.app or by typing ‘XMapTools’ in a terminal.

MacOS update (runtime already installed)

An update replaces the XMapTools application bundle without reinstalling the MATLAB Runtime. This is faster than a full installation and preserves your runtime setup.

Prerequisite: you need the runtime installed. XMapTools must already be installed in /Applications/XMapTools and closed.

MacOS version of XMapTools compatible with Apple Silicon processors (M):

The automatic update only works to update a version of XMapTools based on the MATLAB Runtime 25.1 for macOS Apple Silicon and MATLAB Runtime v99 for macOS Intel. 

MacOS: Uninstall previous MATLAB Runtime

The previous MATLAB Runtime version (v99, v911 or v912) can be uninstalled as it is no longer required to run XMapTools 4.5 on Apple Silicon Macs.

1. Open a Finder window and navigate to Applications/MATLAB/MATLAB_Runtime/.
2. Select the runtime folder and drag it to the Trash.

Windows

Initial Windows XMapTools + runtime installation

The installation of XMapTools 4.5 and MATLAB Runtime can be performed by running this code in a PowerShell with administrator privileges:

The xmaptools.ch is official and used to distribute the compiled version of XMapTools. If you are using XMapTools behind a firewall that blocks access to these, you may have trouble downloading and installing the program. If this is the case, please ask your system admin to add this domain to the firewall allow list. Traffic can be limited to HTTPS.

What happens during installation:

1. Any previous XMapTools installation in C:\Program Files\XMapTools is removed.
2. The installer archive is downloaded and extracted to a temporary directory.
3. The graphical installer (XMapToolsInstaller_Windows.exe) is launched.
4. Press Next.
5. Leave the default installation folder ‘/Program Files/XMapTools’ to allow automatic updates in the future and press Next to continue.
6. Leave the default installation folder for the Runtime ‘/Program Files/MATLAB/MATLAB_Runtime’ and press Next.
7. Click ‘Begin Install’ to install XMapTools and download the runtime (~3 Gb).
8. Press Close.
9. The installation is complete and you can start XMapTools using XMapTools.exe.

Troubleshooting: If you already have Runtime 2025a installed on your computer, you may receive an error message stating that the installer cannot connect to the MATLAB server. If this happens, open a Command Prompt window (cmd) as an administrator (right-click and select ‘Open as administrator’), then type “cd C:\Program Files\MATLAB\MATLAB Runtime” and then “rmdir /s R2025a”.

Windows update

The automatic update of XMapTools to the latest version can be performed after closing XMapTools by simply running this command in a PowerShell terminal (click the Start button, type powershell, right-click Windows PowerShell, and select “Run as administrator”):

The automatic update only works to update a version of XMapTools based on the MATLAB Runtime v99 (XMapTools 4 and later versions).