Linux is AntiMicroX’s primary platform, and version 3.6.1 gives you more official installation routes than most controller tools: Ubuntu .deb packages, a portable AppImage, a Flatpak on Flathub, and distribution packages for Fedora, openSUSE and Arch. AntiMicroX is free and open source under the GPL-3.0-or-later licence, and it maps gamepad buttons and axes to keyboard keys, mouse actions, scripts and macros on both X.org and Wayland sessions, with one documented exception covered below. This guide helps you choose the route that fits your distribution, walks through each one, and finishes with the controller check you should do before building any profile. All of the files and package names here come from the project’s own README and release page, and the same packages are linked from our AntiMicroX download page and summarised in our AntiMicroX on Linux overview. Pick one route and finish it; mixing partial installs from several routes only makes troubleshooting harder later.
Choose your installation route
If you run Ubuntu 22.04 or Ubuntu 24.04, the matching official .deb from GitHub Releases is the most direct option, because the project publishes a separate package built for each of those releases. If you run another distribution, or you do not want a system-level install, the AppImage runs as a single file on any reasonably current x86_64 Linux. If your distribution supports Flatpak and you prefer sandboxed, easily updated applications, the Flathub package is the official Flatpak route, published under the application ID io.github.antimicrox.antimicrox. If you prefer your distribution’s own repositories, Fedora users can install the distro package with dnf, openSUSE publishes a package, and Arch users will find AntiMicroX in the AUR and the chaotic-aur repository. There is no single correct answer: a .deb or distro package integrates most naturally, a Flatpak updates most uniformly across distributions, and an AppImage is the easiest to test or delete. The profiles you create afterwards are ordinary .amgp files and work the same regardless of which route installed the program.
- Ubuntu 22.04 or 24.04: use the matching official .deb package.
- Any x86_64 distribution, no install: use the AppImage.
- Prefer sandboxed updates: use the Flathub Flatpak.
- Fedora, openSUSE or Arch: use your distribution package where available.
Option 1: Install the Ubuntu .deb package
Download the .deb that matches your Ubuntu release from the official GitHub release for 3.6.1: one package is built for Ubuntu 22.04 and another for Ubuntu 24.04, both for x86_64. Using the package that matches your release matters, because the two builds are linked against the libraries of their respective Ubuntu versions. Install the downloaded package with your graphical package installer or with your usual command-line method for local .deb files, allowing the package manager to resolve dependencies from your configured repositories. Version 3.5.1 specifically fixed Debian Qt6 install dependencies and added the Ubuntu 24.04 package, and 3.6.1 makes Qt6 the default build, so current packages expect a Qt6-based system. If the package manager reports a missing dependency, update your package lists and try again rather than forcing the install, because a forced install that leaves broken dependencies will fail in less obvious ways later. When installation finishes, launch AntiMicroX from your applications menu and keep it open while you connect a controller for the check at the end of this guide.
Option 2: Run the AppImage
The AppImage is a single self-contained file, AntiMicroX-x86_64.AppImage, published with the 3.6.1 release. Download it, make it executable in your file manager’s properties or with your terminal, and run it: there is no installation step and nothing is written into system directories. That makes the AppImage ideal for trying AntiMicroX on a distribution without an official package, for keeping the program on removable media, or for testing a new version alongside an installed one. The release also includes a separate debug AppImage and a .zsync update file; normal users should ignore both, because the debug build is larger and intended for reporting problems, and the .zsync file is update metadata rather than a program. Because an AppImage is just a file, removing it is equally simple: delete the file. If the AppImage does not start, the most productive first check is whether other AppImages run on your system at all, which separates a general AppImage or FUSE problem on your machine from anything specific to AntiMicroX itself.
Option 3: Install the Flatpak from Flathub
The official Flatpak is published on Flathub under the ID io.github.antimicrox.antimicrox, and the project README gives the standard Flathub installation command using that ID. Version 3.6.1 was mainly a Flatpak-focused maintenance release: it fixed a crash on X11 for builds made without X11 support and fixed a blank tray icon in the Flatpak package, and it bumped the Qt and SDL2 versions used in release builds. In other words, the current release is a good one to install as a Flatpak. Flatpak is a sensible choice if your distribution is not Ubuntu, Fedora or Arch based, if you want one update mechanism for most of your applications, or if you prefer applications to be sandboxed by default. After installation, launch AntiMicroX normally from your desktop. If a controller is not visible inside the Flatpak, work through your system’s device and Flatpak permission settings before assuming the program is at fault, because sandboxing is precisely the layer that can separate an application from a hardware device on an otherwise healthy system.
Option 4: Use a distribution package
Fedora users can install AntiMicroX from the distribution repositories with dnf, using the package name antimicrox, as documented in the project README. openSUSE also publishes a package through its own software channels. Arch users will find AntiMicroX in the AUR, with the chaotic-aur repository as an alternative binary source; the README notes a repository key step for chaotic-aur, which belongs to that repository’s own setup instructions and is unrelated to the Windows binaries. Distribution packages have one advantage nothing else matches: they update with the rest of your system, using tools you already trust. Their trade-off is timing, because a distribution may package a slightly older version than the latest GitHub release. For a mapping tool, that is usually acceptable, but if you specifically need a fix listed in the 3.6.1 or 3.6.0 notes, such as the D-Bus IPC work added in 3.6.0, compare the packaged version with the release page before you troubleshoot a feature that your package may simply not contain yet.
After installing: check your controller
Whichever route you used, do the same first check. Launch AntiMicroX, connect your controller, and press buttons and move the sticks while watching the main window: the corresponding controls should respond, confirming that SDL2 has recognised the device. AntiMicroX detects controllers through SDL2 and can also generate SDL2 game-controller configurations for unusual gamepads, so recognition at this layer is the foundation for everything else. The project documentation points Linux users to sdl2-jstest and evtest for testing whether the system itself sees the controller when AntiMicroX does not. Work from the system outward: if evtest shows nothing, the problem is below AntiMicroX; if the system sees the device but AntiMicroX does not, check permissions and, for Flatpak, sandbox access. One Wayland note belongs in every Linux setup: AntiMicroX supports Wayland sessions, but Auto Profiles do not work on Wayland, a limitation the project documents itself. Manual profiles work as expected; only the automatic per-application loading is affected. Once detection is confirmed, continue with the beginner’s guide or go straight to creating your first profile.
