Installation Guide

Choose your operating system and follow the steps to install Mantra.

System Requirements Overview

Before installing, ensure your system meets these requirements:

OS	Minimum Version	Architecture	Disk Space
macOS	12.0 (Monterey)	Intel / Apple Silicon	At least 500MB
Windows	10 (version 1903+)	64-bit	At least 500MB
Linux	Ubuntu 22.04+ / Fedora 36+ / Debian 12+	64-bit (x86_64)	At least 500MB

About Disk Space

The installers themselves are roughly 16–96MB depending on format, and the installed application takes about 70–150MB. The 500MB recommendation leaves room for session caches and code snapshot data.

Installer Filename Convention

All installers follow the pattern Mantra_{version}_{platform}-{arch}.{ext}, for example Mantra_0.12.7_macos-arm64.dmg.

Files ending in .sig or .app.tar.gz on the download page are auto-update artifacts — you don't need to download them for a manual install.

macOS Installation

System Requirements

Operating System: macOS 12.0 (Monterey) or later
Processor: Intel or Apple Silicon (M1/M2/M3/M4) — both built natively
Disk Space: At least 500MB available space
Permissions: Administrator privileges required for installation

Option 1: Download DMG Installer (Recommended)

This is the easiest installation method, suitable for most users.

Download the Installer
Visit the Mantra Download Page and download the .dmg file for macOS.
Choose the Right Version
- Apple Silicon (M1/M2/M3/M4): Download Mantra_{version}_macos-arm64.dmg
- Intel Mac: Download Mantra_{version}_macos-x64.dmg
Not sure which Mac you have? Click the Apple menu → "About This Mac" to check the "Chip" or "Processor" information.
💡 The download page detects your chip automatically and recommends the matching version.
Open the Installer
Double-click the downloaded .dmg file to open the installation window.
Install the Application
Drag the Mantra icon to the Applications folder.
First Launch
Open the Applications folder, find Mantra, and double-click to launch.
App is Notarized by Apple
Mantra is signed with an Apple Developer ID and notarized, so you can simply double-click to launch it — you won't see "developer cannot be verified" or similar security warnings.

Option 2: Using Homebrew (Not Yet Available)

Not Yet Available

Homebrew installation is being prepared. Please use the DMG download from the official website for now.

If you have Homebrew installed, you can quickly install via command line:

bash

brew install --cask mantra

Advantages of Homebrew Installation

One command to install
Easy updates: brew upgrade --cask mantra
Unified application management

Update Mantra:

bash

brew upgrade --cask mantra

Uninstall Mantra:

bash

brew uninstall --cask mantra

Windows Installation

System Requirements

Operating System: Windows 10 (version 1903+) or later
Architecture: 64-bit system (x64)
Disk Space: At least 500MB available space
Permissions: Administrator privileges required for installation

How to Check System Architecture

Press Win + I to open Settings → System → About, and check if "System type" shows "64-bit operating system."

Windows 7/8 Not Supported

Due to technical limitations, Mantra does not support Windows 7 or Windows 8/8.1.

Windows ships two installer formats with identical functionality — pick whichever fits:

Format	Filename	Size	Best For
EXE (NSIS)	`Mantra_{version}_windows-x64-setup.exe`	~16MB	Individual users; wizard supports English and Simplified Chinese
MSI (WiX)	`Mantra_{version}_windows-x64.msi`	~21MB	Enterprise deployment; supports Group Policy and silent install

Option 1: EXE Installer (Recommended for Individuals)

Download the Installer
Visit the Mantra Download Page and download Mantra_{version}_windows-x64-setup.exe.
Run the Installer
Double-click the downloaded .exe file to launch the setup wizard. The wizard supports both English and Simplified Chinese — you can pick a language at startup.
Windows SmartScreen Notice
On first run, Windows SmartScreen may display "Windows protected your PC."
Solution:
1. Click "More info"
2. Click "Run anyway"
This appears because the application hasn't been signed by Microsoft yet, but downloads from the official website are safe.
Complete Installation
Follow the setup wizard prompts to choose the installation location and complete the installation.
Launch Mantra
After installation, you can launch Mantra by:
- Searching for "Mantra" in the Start menu
- Double-clicking the desktop shortcut (if created)

Option 2: MSI Package (Recommended for Enterprise)

The MSI format suits environments that deploy software in bulk via Group Policy (GPO), SCCM, or similar tooling.

Download the Package
Visit the Mantra Download Page and download Mantra_{version}_windows-x64.msi.
Interactive Install
Double-click the .msi file and follow the prompts.

Silent Install (Bulk Deployment)

Run from an elevated Command Prompt or PowerShell:

powershell

# Silent install, no UI
msiexec /i Mantra_0.12.7_windows-x64.msi /quiet /norestart

# Silent install to a specific directory
msiexec /i Mantra_0.12.7_windows-x64.msi /quiet INSTALLDIR="D:\Apps\Mantra"

# Silent install with verbose logging (for troubleshooting deployments)
msiexec /i Mantra_0.12.7_windows-x64.msi /quiet /l*v install.log

Silent Uninstall

powershell

msiexec /x Mantra_0.12.7_windows-x64.msi /quiet

MSI Wizard Language

The MSI installer wizard is currently English-only, but the application itself fully supports English and Chinese — switch it in Settings after first launch. If you need a Chinese installer wizard, use the EXE version.

Option 3: Using Scoop (Not Yet Available)

Not Yet Available

Scoop installation is being prepared. Please use the installer download from the official website for now.

Scoop is a command-line installer for Windows. If you have Scoop installed:

powershell

scoop bucket add extras
scoop install mantra

Update Mantra:

powershell

scoop update mantra

Uninstall Mantra:

powershell

scoop uninstall mantra

Option 4: Using Winget (Not Yet Available)

Not Yet Available

Winget installation is being prepared. Please use the installer download from the official website for now.

Windows 10/11 includes the built-in package manager Winget:

powershell

winget install Mantra.Mantra

Update Mantra:

powershell

winget upgrade Mantra.Mantra

Uninstall Mantra:

powershell

winget uninstall Mantra.Mantra

Linux Installation

System Requirements

Distributions: Ubuntu 22.04+, Debian 12+, Fedora 36+, Arch Linux, or other distributions of comparable recency
Architecture: 64-bit (x86_64)
Disk Space: At least 500MB available space
Dependencies: WebKit2GTK 4.1, GTK 3, libayatana-appindicator (AppImage bundles most dependencies)

About the Distribution Floor

Mantra is built against WebKit2GTK 4.1, with Ubuntu 22.04 as the official build environment. Older distributions (Ubuntu 20.04, Debian 11) only ship WebKit2GTK 4.0 and cannot run the DEB/RPM builds. On those systems, use the AppImage or upgrade your distribution.

Linux ships three installer formats with identical functionality:

Format	Filename	Size	Best For
DEB	`Mantra_{version}_linux-x64.deb`	~26MB	Debian / Ubuntu / Mint, integrates with the system menu
RPM	`Mantra_{version}_linux-x64.rpm`	~26MB	Fedora / RHEL / openSUSE, integrates with the system menu
AppImage	`Mantra_{version}_linux-x64.AppImage`	~96MB	Any distribution, portable with no install

Which Should I Pick?

On Debian/Ubuntu or Fedora-family distributions, prefer DEB or RPM — they're a quarter the size of the AppImage and register themselves in your application menu automatically. The AppImage is larger because it bundles the entire runtime, which is what buys it cross-distribution portability.

Option 1: DEB Package (Recommended for Debian / Ubuntu)

For Debian 12+, Ubuntu 22.04+, Linux Mint 21+, and other Debian-based distributions.

Download the DEB Package
Visit the Mantra Download Page or GitHub Releases and download Mantra_{version}_linux-x64.deb.

Install

bash

# Install with apt (recommended — resolves dependencies automatically)
sudo apt install ./Mantra_0.12.7_linux-x64.deb

# Or with dpkg
sudo dpkg -i Mantra_0.12.7_linux-x64.deb
# If dependencies are reported missing, run
sudo apt-get install -f

Prefer apt Over dpkg

apt install ./xxx.deb resolves and installs missing dependencies for you; dpkg -i does not, leaving you to repair them afterwards.

Launch the Application
After installing, search for "Mantra" in your application menu, or run from a terminal:
bash
```
mantra
```

Option 2: RPM Package (Recommended for Fedora / RHEL)

For Fedora 36+, RHEL 9+, openSUSE, and other RPM-based distributions.

Download the RPM Package
Visit the Mantra Download Page or GitHub Releases and download Mantra_{version}_linux-x64.rpm.

Install

bash

# Fedora / RHEL 9+
sudo dnf install ./Mantra_0.12.7_linux-x64.rpm

# openSUSE
sudo zypper install ./Mantra_0.12.7_linux-x64.rpm

Launch the Application
After installing, search for "Mantra" in your application menu, or run from a terminal:
bash
```
mantra
```

Option 3: AppImage (No Install, Universal)

AppImage is a portable application format that runs without installation on any Linux distribution — including systems whose WebKit2GTK is too old to run the DEB/RPM builds.

Download AppImage
Visit the Mantra Download Page and download Mantra_{version}_linux-x64.AppImage.

Add Execute Permission

bash

chmod +x Mantra_0.12.7_linux-x64.AppImage

Run the Application
bash
```
./Mantra_0.12.7_linux-x64.AppImage
```
Integrating Into the Application Menu
AppImages don't appear in your application menu by default. On first run, Mantra offers to integrate itself with your desktop environment (v0.12.2+ fixed icon and name display). You can also use AppImageLauncher to manage them centrally.

Advantages of AppImage

No root privileges required
Doesn't affect other system software
Easy to try different versions
Can be run from any location
Works on older distributions where DEB/RPM won't install

Option 4: AUR (Not Yet Available)

Not Yet Available

AUR package is being prepared. Please use AppImage for now.

Arch Linux users can install from the AUR:

bash

# Using yay
yay -S mantra-bin

# Or using paru
paru -S mantra-bin

Option 5: Flatpak (Not Yet Available)

Not Yet Available

Flatpak installation is being prepared. Please use AppImage for now.

If your system supports Flatpak:

bash

flatpak install flathub dev.mantra.Mantra

Run:

bash

flatpak run dev.mantra.Mantra

Option 6: Snap (Not Yet Available)

Not Yet Available

Snap installation is being prepared. Please use AppImage for now.

If your system supports Snap:

bash

sudo snap install mantra

Installation Verification

After installation, verify that Mantra is installed correctly.

Launch the Application

Launch Mantra, and you should see the welcome screen:

Version Check

Check your current version inside the app: Settings → General → About Mantra. This shows the version number and lets you check for updates manually.

Mantra Has No Command-Line Tool

Mantra is a pure GUI application and does not provide command-line flags like mantra --version. On Linux, a DEB/RPM install does let you type mantra in a terminal to start the app, but it only opens the graphical window — it does not accept command-line arguments.

Signs of Successful Installation

[x] Application launches normally
[x] Welcome screen displays correctly
[x] System Tray (v0.7.0+): After closing the main window, the tray icon should remain, indicating the app is running in the background
[x] Can create new projects or open existing ones

Automatic Updates

Starting from v0.8.0, Mantra includes a built-in auto-update system:

Auto Check: Checks for new versions automatically on startup.
Background Download: New versions are downloaded silently in the background without interrupting your work.
One-Click Restart: Once downloaded, a notification badge appears on the Settings button. Click to restart and install the new version.

You can also manually check for updates in Settings -> General -> About Mantra.

Troubleshooting

macOS Common Issues

"Mantra" cannot be opened because the developer cannot be verified

Cause: macOS Gatekeeper blocks apps that haven't been notarized. The current release is notarized, so you shouldn't see this prompt; it may still appear with older versions or installers from unofficial sources.

Solution:

Right-click the Mantra application
Select "Open"
Click "Open" in the dialog

Or in System Settings:

Open "System Settings" → "Privacy & Security" ("System Preferences" → "Security & Privacy" on macOS 12)
Click "Open Anyway"

Downloading the latest version from the official website avoids this prompt.

"Mantra" is damaged and can't be opened

Cause: Some download tools may corrupt the file's extended attributes.

Solution: Run the following command in Terminal to remove the quarantine attribute:

bash

xattr -cr /Applications/mantra.app

Note the Lowercase App Name

Once installed into Applications, the actual bundle name is mantra.app (lowercase). If the command above reports that the path doesn't exist, confirm the real name first:

bash

ls -d /Applications/*antra*.app

:::

Apple Silicon Mac starts slowly or won't launch

Cause: You may have downloaded the Intel version instead of the ARM version, in which case the app runs through Rosetta 2 translation with noticeably worse performance.

Solution: Make sure the filename contains macos-arm64 (not macos-x64).

"Requires macOS 12.0 or later" message

Cause: Mantra requires macOS 12.0 (Monterey) at minimum.

Solution: Click the Apple menu → "About This Mac" to check your version. If it's below 12.0, you'll need to upgrade macOS first.

Windows Common Issues

Windows SmartScreen blocks the application

Cause: The application hasn't received Microsoft signature certification.

Solution:

Click the "More info" link
Click "Run anyway"

Ensure you download from the official website for safety.

"This app can't run on your PC" error during installation

Cause: You may have downloaded the wrong version, or your system is not 64-bit.

Solution:

Confirm your system is 64-bit (Settings → System → About)
Re-download the correct installer (filename contains windows-x64)

MSI silent install fails with no output

Cause: /quiet mode suppresses all error messages, and the install requires administrator privileges.

Solution:

Confirm you're running Command Prompt or PowerShell as Administrator

Re-run with logging enabled, then inspect the log:

powershell

msiexec /i Mantra_0.12.7_windows-x64.msi /quiet /l*v install.log

Search install.log for Return value 3 — the actual failure reason is usually a few lines above it

Missing VCRUNTIME140.dll or other DLL files

Cause: Missing Visual C++ runtime library.

Solution: Download and install the Microsoft Visual C++ Redistributable.

Linux Common Issues

AppImage won't run

Cause: Execute permission not added or FUSE is missing.

Solution:

bash

# Add execute permission
chmod +x Mantra_0.12.7_linux-x64.AppImage

# If it still won't run, install FUSE
# Ubuntu/Debian
sudo apt install fuse libfuse2

# Fedora
sudo dnf install fuse fuse-libs

DEB/RPM package installed but won't launch

Cause: Missing dependencies — most commonly a WebKit2GTK version mismatch.

Solution:

bash

# Debian/Ubuntu - fix dependencies
sudo apt-get install -f

# Check whether WebKit2GTK 4.1 is present (Mantra requires this version)
apt list --installed | grep webkit2gtk    # Debian/Ubuntu
dnf list installed | grep webkit2gtk      # Fedora

# Launch from a terminal to see the error output
mantra

If it reports a missing libwebkit2gtk-4.1.so, your distribution is too old (it only ships 4.0). Use the AppImage instead, or upgrade to Ubuntu 22.04+ / Debian 12+ / Fedora 36+.

Display issues (blurry interface or abnormal scaling)

Cause: High DPI screen scaling issues.

Solution: Try launching with these environment variables:

bash

# Method 1: Force scaling
GDK_SCALE=2 ./Mantra_0.12.7_linux-x64.AppImage

# Method 2: Adjust DPI scaling
GDK_DPI_SCALE=0.5 ./Mantra_0.12.7_linux-x64.AppImage

The same applies to DEB/RPM installs — just prefix the mantra command with the environment variables.

Uninstall Instructions

macOS Uninstall

Manual Uninstall:

Quit the Mantra application
Open Finder → Applications
Drag Mantra to the Trash

(Optional) Delete configuration files:

bash

rm -rf ~/Library/Application\ Support/com.gonewx.mantra
rm -rf ~/Library/Preferences/com.gonewx.mantra.plist

Uninstall with Homebrew (Homebrew installation is not yet available):

bash

brew uninstall --cask mantra

Windows Uninstall

Open "Settings" → "Apps" → "Installed apps"
Search for "Mantra"
Click "..." → "Uninstall"
Follow the prompts to complete uninstallation

Or via Control Panel:

Open "Control Panel" → "Programs" → "Programs and Features"
Find Mantra, right-click and select "Uninstall"

Uninstall with Package Managers:

MSI silent uninstallScoop (Not Yet Available)Winget (Not Yet Available)

powershell

msiexec /x Mantra_0.12.7_windows-x64.msi /quiet

powershell

scoop uninstall mantra

powershell

winget uninstall Mantra.Mantra

Linux Uninstall

AppImage: Simply delete the AppImage file.

bash

rm Mantra_0.12.7_linux-x64.AppImage

If you previously integrated it with your desktop, also remove the generated shortcut:

bash

rm -f ~/.local/share/applications/*mantra*.desktop

DEB Package:

bash

sudo apt remove mantra
# Or completely remove (including configuration)
sudo apt purge mantra

RPM Package:

bash

sudo dnf remove mantra
# openSUSE
sudo zypper remove mantra

Flatpak:

bash

flatpak uninstall dev.mantra.Mantra

Snap:

bash

sudo snap remove mantra

Delete Configuration Files (Optional):

bash

rm -rf ~/.config/com.gonewx.mantra
rm -rf ~/.local/share/com.gonewx.mantra

Next Steps

After installation, read the Getting Started guide to learn how to use Mantra.

Having Issues?

If the troubleshooting steps above don't solve your problem:

Check the FAQ
Visit GitHub Issues to search or submit issues
Join the Community Discussion

Installation Guide ​

System Requirements Overview ​

macOS Installation ​

System Requirements ​

Option 1: Download DMG Installer (Recommended) ​

Option 2: Using Homebrew (Not Yet Available) ​

Windows Installation ​

System Requirements ​

Option 1: EXE Installer (Recommended for Individuals) ​

Option 2: MSI Package (Recommended for Enterprise) ​

Option 3: Using Scoop (Not Yet Available) ​

Option 4: Using Winget (Not Yet Available) ​

Linux Installation ​

System Requirements ​

Option 1: DEB Package (Recommended for Debian / Ubuntu) ​

Option 2: RPM Package (Recommended for Fedora / RHEL) ​

Option 3: AppImage (No Install, Universal) ​

Option 4: AUR (Not Yet Available) ​

Option 5: Flatpak (Not Yet Available) ​

Option 6: Snap (Not Yet Available) ​

Installation Verification ​

Launch the Application ​

Version Check ​

Signs of Successful Installation ​

Automatic Updates ​

Troubleshooting ​

macOS Common Issues ​

Windows Common Issues ​

Linux Common Issues ​

Uninstall Instructions ​

macOS Uninstall ​

Windows Uninstall ​

Linux Uninstall ​

Next Steps ​

Installation Guide

System Requirements Overview

macOS Installation

System Requirements

Option 1: Download DMG Installer (Recommended)

Option 2: Using Homebrew (Not Yet Available)

Windows Installation

System Requirements

Option 1: EXE Installer (Recommended for Individuals)

Option 2: MSI Package (Recommended for Enterprise)

Option 3: Using Scoop (Not Yet Available)

Option 4: Using Winget (Not Yet Available)

Linux Installation

System Requirements

Option 1: DEB Package (Recommended for Debian / Ubuntu)

Option 2: RPM Package (Recommended for Fedora / RHEL)

Option 3: AppImage (No Install, Universal)

Option 4: AUR (Not Yet Available)

Option 5: Flatpak (Not Yet Available)

Option 6: Snap (Not Yet Available)

Installation Verification

Launch the Application

Version Check

Signs of Successful Installation

Automatic Updates

Troubleshooting

macOS Common Issues

Windows Common Issues

Linux Common Issues

Uninstall Instructions

macOS Uninstall

Windows Uninstall

Linux Uninstall

Next Steps