🌐 English|한국어

Installation

This guide provides instructions for installing Modan2 on different operating systems.

System Requirements

Minimum Requirements:

  • Operating System: Windows 10/11, macOS 10.14+, or Linux (Ubuntu 20.04+, Fedora 34+)

  • RAM: 4 GB (8 GB recommended for large datasets)

  • Disk Space: 500 MB for application + space for your data

  • Display: 1280x720 resolution (1920x1080 recommended)

For 3D Visualization:

  • OpenGL 3.3+ compatible graphics card

  • Up-to-date graphics drivers

Installation Methods

Modan2 is distributed as a prebuilt package for each platform on the releases page. Every file carries the version and build number, so the exact names change from release to release — <version> and <build> below stand for what you see on the release you are downloading (for example v0.1.12 and build672).

Each release also publishes SHA256SUMS.txt if you want to verify a download.

Warning

Only the Windows build is well tested. The macOS and Linux packages are produced by the same automated build, but they have not been through the same testing, so you may hit problems that do not occur on Windows. If one of them fails for you, please report it on the issues page.

Windows

  1. Download Modan2-Windows-Installer-v<version>-build<build>.zip from the releases page.

  2. Extract the ZIP. It contains a single installer, Modan2_v<version>_build<build>_Installer.exe.

  3. Run the installer and follow the wizard. It installs for the current user only and does not ask for administrator rights.

  4. Launch Modan2 from the Start Menu.

Note

Windows Defender may warn about an unsigned executable. Click “More info” → “Run anyway” if you trust the source.

Note

If you have a version older than 0.2.0-beta.2 installed, the installer detects it and offers to remove it first. Accept unless you have a reason to keep both — see Updating Modan2.

Note

A portable (no-install) Windows build is not currently published — the installer is the only Windows package.

macOS

  1. Download Modan2-macOS-Installer-v<version>-build<build>.dmg from the releases page.

  2. Open the DMG.

  3. Drag Modan2.app into your Applications folder.

  4. Launch it from Applications.

Note

On first launch, right-click the app and choose “Open” to get past the Gatekeeper warning shown for unsigned applications.

Linux

Linux is distributed as an AppImage, which runs without installation.

# Download Modan2-Linux-v<version>-build<build>.AppImage from the releases page
chmod +x Modan2-Linux-v<version>-build<build>.AppImage
./Modan2-Linux-v<version>-build<build>.AppImage

Note

If the AppImage does not start, your distribution may be missing FUSE. Either install it (sudo apt-get install libfuse2 on Ubuntu/Debian) or run the AppImage with --appimage-extract-and-run.

Troubleshooting

Windows: missing DLL on startup

Symptom: the application does not start and reports a missing DLL.

Install the Microsoft Visual C++ Redistributable (x64), which the packaged build depends on and which some clean Windows installations lack: https://aka.ms/vs/17/release/vc_redist.x64.exe

macOS: “Modan2 is damaged and can’t be opened”

This is Gatekeeper’s quarantine attribute on an unsigned application, not actual damage. Remove it:

sudo xattr -rd com.apple.quarantine /Applications/Modan2.app

Linux: “Could not load the Qt platform plugin xcb”

Qt ships its own libqxcb.so, which links against system XCB libraries. If any is missing the plugin cannot load.

sudo apt-get install -y libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \
  libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-xfixes0 \
  libxcb-shape0 libxcb-cursor0 libxkbcommon-x11-0

To find out which one is missing, ask Qt:

QT_DEBUG_PLUGINS=1 ./Modan2-Linux-<version>.AppImage

OpenGL / 3D Rendering Errors

Symptom: the 3D viewer is blank, or the application reports an OpenGL error on startup.

  • Update your graphics drivers.

  • Check that your GPU supports OpenGL 3.3 or newer.

  • On Linux, a headless or remote session (SSH, VNC, some WSL setups) may not expose a usable OpenGL context; run Modan2 on a normal desktop session.

Performance Issues

Slow startup or rendering:

  • Update graphics drivers

  • Reduce dataset size (split large datasets)

  • Close other GPU-intensive applications

  • Increase system RAM if working with large 3D models

High memory usage:

  • Close unused datasets

  • Limit the number of objects loaded simultaneously

  • Use lower resolution images for preview

Verifying Installation

After installation, verify that Modan2 works correctly:

  1. Launch the application

    • Windows: Start Menu → Modan2

    • macOS: Applications → Modan2

    • Linux: run the AppImage

  2. Create a test dataset

    • Click “New Dataset” (Ctrl+N)

    • Name it “Test”

    • Click OK

  3. Import example data

    • Download example TPS file from examples/

    • Drag and drop into your dataset

  4. Run a simple analysis

    • Select dataset → “Analyze Dataset”

    • Choose PCA

    • Verify that results display correctly

If all steps complete without errors, your installation is successful!

Updating Modan2

Download the package for the new release and install it the same way as before:

  • Windows: run the new installer; it replaces the old version.

  • macOS: open the new DMG and replace Modan2.app in Applications.

  • Linux: download the new AppImage and run it instead of the old one.

Your database, data files and preferences are kept separately from the application, so updating does not touch them.

Updating from 0.2.0-beta.1 or earlier (Windows)

0.2.0-beta.2 changed where Modan2 installs and how it identifies itself, so the installer cannot recognise a copy left by an earlier release. It detects one and offers to remove it; accepting is the simple path.

If you decline and keep both, remove the old one before you install the new one, not after. The Start Menu shortcut and the example datasets live at fixed paths that both installations share. Installing the new version takes them over, but the old uninstaller still believes it owns them, so running it afterwards deletes the shortcut that now points at the new version and removes the example datasets.

Your own data is never involved either way — it lives outside both program folders.

Uninstalling Modan2

  • Windows: Settings → Apps → Modan2 → Uninstall.

  • macOS: drag Modan2.app from Applications to the Trash.

  • Linux: delete the AppImage file.

This leaves your data untouched, which is usually what you want. Datasets, images, 3D models, logs, backups and preferences all live in ~/PaleoBytes/Modan2/ (on Windows, C:\Users\<you>\PaleoBytes\Modan2). Delete that folder as well if you want to remove everything — but note that it holds the only copy of your datasets.

Getting Help

If you encounter issues not covered here:

  1. Check the GitHub Issues page

  2. Search for similar problems in closed issues

  3. Create a new issue with: - Your OS and version - The Modan2 version and build number you downloaded - Full error message - Steps to reproduce

Next Steps