mono: Run .NET apps on Linux

Mono lets you run many .NET Framework executables on Linux and other platforms. This quick guide shows practical usage, common pitfalls, and where things can go wrong.

Quickstart: run a program

  • Basic run: executes a .NET assembly
mono {{path/to/program.exe}}
  • Run with debugging hooks (useful when diagnosing crashes or exceptions):
mono --debug {{path/to/program.exe}}
  • Example from a real path
mono /home/user/apps/MyApp.exe

prerequisites: install Mono

  • On Debian/Ubuntu
sudo apt update
sudo apt install -y mono-complete
  • On Fedora
sudo dnf install -y mono-complete
  • Verify installation
mono --version

Notes:

  • mono-complete is a convenient meta-package that pulls in the runtime, libraries, and development tools you’ll likely need.
  • If you only need the runtime, you can install mono-runtime to keep things lighter.

When Mono works and when it doesn’t

  • Works well for many classic .NET Framework apps, especially those that don’t rely on Windows-only APIs.
  • May fail with:
    • Windows-only libraries or COM interop that Mono cannot provide.
    • WPF, Windows Forms requiring specific GUI stacks or newer .NET features not supported by Mono.
    • Strongly depend on specific .NET Framework versions beyond Mono’s current compatibility.

Tip: if an app targets a very old or very new .NET Framework, check Mono’s compatibility notes for that version.

Troubleshooting common pitfalls

  • Missing libraries or native dependencies: some apps call into native DLLs. Install common 32-bit libraries if you get “wrong architecture” errors.
# Example (Ubuntu 64-bit with 32-bit dependencies)
sudo apt install -y libtcmalloc-minimal4:i386 zlib1g:i386

  • Permissions: ensure the executable and any required DLLs are readable by you. Run as your user; avoid running GUI apps as root.

  • Debugging crashes: capture logs and use —debug to get more trace output. You can redirect logs to a file:

mono --debug {{path/to/program.exe}} &> mono.log

Performance tips

  • Use mono —gc=boehm or —gc=hybrid to adjust GC strategy if you see pauses or memory issues (advanced).
  • For long-running server apps, profile with Mono’s profiling tools to identify bottlenecks.

Next steps

  • Explore Mono’s documentation for Windows Forms, ASP.NET, and other supported workloads.
  • If your app targets .NET Core/.NET 5+/modern runtimes, consider using dotnet instead of Mono where appropriate.

See Also