Vaibhav Shende Vaibhav Shende

Running Micromouse Simulator on Ubuntu: Complete FUSE Resolution Guide

Three verified methods to resolve libfuse.so.2 errors and run the mms AppImage on modern Linux systems.

Technical

Running Micromouse Simulator on Ubuntu: Complete FUSE Resolution Guide

The Problem: What is FUSE?

When you first try to run the Micromouse simulator AppImage on Ubuntu, you encounter this error:

dlopen(): error loading libfuse.so.2
 
AppImages require FUSE to run.
You might still be able to extract the contents of this AppImage
if you run it with the --appimage-extract option.
See https://github.com/AppImage/AppImageKit/wiki/FUSE
for more information

This happens because AppImages use FUSE (Filesystem in Userspace) to mount themselves as virtual filesystems. Modern Ubuntu (22.04+, 24.04+, and newer) ships with FUSE 3 by default, but most AppImages—including mms—were built for FUSE 2, which is no longer installed.

Why three methods? Each has different trade-offs:

  • Method 1: One-time setup, native execution, best user experience
  • Method 2: No installation, slower startup, no permanent storage
  • Method 3: Hybrid: extract once, runs fast, works everywhere

Quick Fix Overview

Ubuntu 24.04+

sudo apt update
sudo apt install libfuse2t64
./mms-x86_64.AppImage

Ubuntu 22.04 and Earlier

sudo apt update
sudo apt install libfuse2
./mms-x86_64.AppImage

Initial Setup

Step 1: Download and Extract

Start by downloading the mms release v1.2.0:

  1. Download linux.zip from github.com/mackorone/mms/releases
  2. Extract the ZIP file: 
    sudo apt install unzip
unzip linux.zip
  3. Navigate to the extracted directory and make the AppImage executable: 
    cd linux
chmod +x mms-x86_64.AppImage

Now you’re ready to choose a method below. Try Method 1 first—it’s the recommended approach.

Method 1: Install FUSE Library (Recommended) ⭐

Why This Method?

This is the preferred approach for regular desktop usage. It’s a one-time installation that restores native AppImage functionality, allowing files to run directly via double-click or terminal execution without any modification.

Pros:

  • Native AppImage execution
  • One-time setup
  • Works system-wide
  • Fast startup

Cons:

  • Requires sudo
  • Installs system package
  • Slight disk usage (~10MB)

Installation Instructions by Distribution

Ubuntu 24.04, 24.10, 25.04, 26.04 and Newer

Ubuntu 24.04 and later renamed the package to libfuse2t64 to support the time64 ABI:

sudo apt update
sudo apt install libfuse2t64

If libfuse2t64 is unavailable, try the fallback:

sudo apt install libfuse2

Ubuntu 22.04 and Earlier, Linux Mint, Debian

sudo apt update
sudo apt install libfuse2

Verify Installation

Once installed, run the AppImage directly:

./mms-x86_64.AppImage

The Micromouse simulator window should open. You’re done with this method!

Safety Note: Installing libfuse2 or libfuse2t64 does not break your system. These are compatibility libraries that coexist safely with FUSE 3.

Method 2: Extract and Run (One-time, Temporary)

Why This Method?

Use this method if you cannot or prefer not to install FUSE. The AppImage is extracted on-the-fly, executed, and automatically cleaned up when the app closes. No permanent disk usage.

Pros:

  • No system packages
  • No disk storage
  • Works everywhere
  • No sudo required

Cons:

  • Slower startup
  • Extract overhead every run
  • Extraction to /tmp

2A: Using Command-Line Argument

Run the AppImage with the --appimage-extract-and-run flag:

./mms-x86_64.AppImage --appimage-extract-and-run

You can pass additional arguments to the application after this flag.

2B: Using Environment Variable

Alternatively, set the APPIMAGE_EXTRACT_AND_RUN environment variable:

export APPIMAGE_EXTRACT_AND_RUN=1
./mms-x86_64.AppImage

To persist this for a single command:

APPIMAGE_EXTRACT_AND_RUN=1 ./mms-x86_64.AppImage

Best for: Testing, CI/CD pipelines, Docker containers, or systems where you lack root privileges.

Method 3: Permanent Extraction

Why This Method?

Manually extract the AppImage once and run directly from the extracted files. This gives you the speed of native execution with the flexibility of full control over the application contents.

Pros:

  • Fast startup (no re-extraction)
  • Can modify contents
  • Works on all systems
  • Great for debugging

Cons:

  • Permanent disk usage (~100-500MB)
  • Manual re-extraction on updates
  • More setup steps

Step-by-Step Instructions

Step 1: Extract the Contents

Run the AppImage with the --appimage-extract flag:

cd linux
chmod +x mms-x86_64.AppImage
./mms-x86_64.AppImage --appimage-extract

This creates a folder named squashfs-root in your current directory.

Step 2: Run the Application

Navigate into the extracted directory and execute the binary:

cd squashfs-root
chmod +x mms
./mms

The simulator window should open. From now on, you only need to run ./mms from the squashfs-root directory.

Step 3: (Optional) Desktop Integration

To integrate the extracted app into your system application menu:

  1. Copy the .desktop file:

    cp squashfs-root/*.desktop ~/.local/share/applications/

  2. Edit the .desktop file:

    nano ~/.local/share/applications/mms.desktop

  3. Update with absolute paths:

    [Desktop Entry]
Type=Application
Name=Micromouse Simulator
Exec=/home/YOUR_USERNAME/path/to/squashfs-root/mms
Icon=/home/YOUR_USERNAME/path/to/squashfs-root/32x32.png
Categories=Utility;Education;
Comment=Micromouse Robot Navigation Simulator

  4. Restart your desktop shell (GNOME: Alt+F2, type “r”, press Enter)

Once complete, the Micromouse Simulator will appear in your “Show Applications” menu.

Next Steps: Running Your Algorithm

Once the simulator is running, you’re ready to test your navigation algorithm.

Step 1: Clone Your Repository

git clone https://github.com/svaibhav101/MicroMouse-Goal-Navigation.git
cd MicroMouse-Goal-Navigation
# Follow the build instructions in the repository

Step 2: Build Your Project

Follow the project’s build instructions to compile your C++ code.

Step 3: Configure the Simulator

  1. Open the Micromouse Simulator
  2. Click the + symbol to create a new configuration
  3. Fill in the “Edit Mouse Algorithm” dialog:
    • Name: Give your configuration a name (e.g., “My Algorithm v1”)
    • Directory: Path to your build folder
    • Run Command: Name of your executable (e.g., “mouse_algorithm”)
    • Build Command: Leave empty
  4. Click OK

Step 4: Build and Test

  1. Write and build your code in Visual Studio Code
  2. Return to the mms simulator window
  3. Click Run to execute your algorithm
  4. Iterate and refine your navigation logic

Tip: Keep the simulator and VS Code windows side-by-side for fast development cycles.

Troubleshooting

Still Getting FUSE Error?

Verify the library is installed:

# For Ubuntu 24.04+
dpkg -l | grep libfuse2t64
 
# For Ubuntu 22.04 and earlier
dpkg -l | grep libfuse2

If the package isn’t listed, try the installation command again. You may need to add the universe repository:

sudo add-apt-repository universe
sudo apt update

AppImage Still Won’t Run?

Use Method 3 (permanent extraction) or Method 2 (temporary extraction) as a fallback.

Permission Denied When Running?

Ensure the executable has execute permissions:

chmod +x mms-x86_64.AppImage
# or for Method 3:
cd squashfs-root && chmod +x mms

Resources

Last updated: June 2026 | Methods tested on Ubuntu 22.04, 24.04, and 26.04

Back to Blog