Windows installation

The Windows installer includes muSRFlow, ROOT, and musrfit. Install WSL2 first; muSRFlow prepares its own Linux runtime on first launch. You do not need Node.js, npm, Ubuntu, or a separate ROOT/musrfit installation.

Already installed muSRFlow? Read Existing installations as well: updating the application does not update an already imported WSL runtime.

Before you start

  • Use a 64-bit Intel/AMD PC. The current package is x64.

  • Windows 11 is recommended. Windows 10 requires build 19044 or newer for WSLg, which displays the musrview spectrum windows.

  • Administrator access is needed to enable the Windows virtualization features.

  • Obtain the Windows installer, named muSRFlow-<version>-x64.exe, from the project’s Releases or the musrflow-windows package in Packages. Verify its SHA-256 checksum against the accompanying .sha256 file. The Windows installer includes the bundled runtime (musrfit, musrt0, musrview, msr2data, dump_header, root-config) for use inside WSL2; only markers are placed in the app resources.

  • For a test build that has not been published yet, download the musrflow-windows-x64 artifact from a successful Build Windows installer workflow run and extract the installer.

Avoid old rc.5 installers. Early builds lack the WSL fixes. The current runner-built installer includes them and has passed Windows installation, runtime setup, data download, Fit/Plot, and multi-run smoke tests.

See Microsoft’s WSL GUI requirements for the Windows prerequisites.

Install step by step

  1. Install WSL. Open PowerShell as Administrator and run:

    wsl --install --no-distribution
    

    Restart Windows afterwards. Skip this step if WSL is already installed. muSRFlow supplies its own distribution, so Ubuntu is not required.

  2. Update and check WSL. In administrator PowerShell, run:

    wsl --update
    wsl --version
    

    Follow any restart instructions. The output should include WSL and WSLg. These commands are described in the Microsoft WSL command reference.

  3. Install muSRFlow. Double-click the Windows installer and complete setup. The runtime archive muSRFlow-runtime-rootfs.tar.gz is included; do not extract or import it manually for a normal installation.

  4. Launch muSRFlow from the Start menu using your normal Windows account. First launch imports the runtime as muSRFlow-runtime and can take several minutes. Fit and Plot wait until preparation finishes. Afterwards, verify in PowerShell:

    wsl --list --verbose
    

    The list should contain muSRFlow-runtime with VERSION 2. Running and Stopped are both normal when idle. The runtime is stored under %LOCALAPPDATA%\muSRFlow\muSRFlow-runtime for this account.

  5. Choose work and data folders before fitting. Create folders such as:

    C:\Users\<your-name>\muSRFlow\work
    C:\Users\<your-name>\muSRFlow\data
    

    In File / Preferences, select them as Work directory and Data directory. Leave musrfit binaries and musrfit startup XML on automatic detection, then save. Enter normal Windows paths; muSRFlow translates them for WSL.

    Use a work folder outside the application installation directory. The default . can resolve to the installation folder and place your results among files managed by the installer.

  6. Try Plot, then Fit. Select a known instrument, year, and run. Click Plot and confirm that the spectrum window opens. Missing run data can be downloaded from musruser.psi.ch after confirmation when the server is reachable. Then click Fit, check that the parameter table updates, and inspect the generated files in your work directory.

Existing installations

  1. Preserve any MSR/data/result files currently stored inside the muSRFlow installation folder: move them to a separate work folder before upgrading.

  2. Close muSRFlow and install the refreshed Windows application.

  3. If your runtime was imported from an older bundle, add the missing Boost headers from PowerShell:

    wsl -d muSRFlow-runtime -- dnf -y install boost-devel
    

    This needs access to the distribution’s package repositories. ROOT uses these headers when loading musrview plotting classes. Fresh runtimes from the corrected installer already include them.

  4. Reopen muSRFlow, select your work directory in Preferences, and retry Plot and Fit.

Reinstalling the application preserves an existing muSRFlow-runtime distribution, so the application update alone does not add those headers. The command above repairs it in place; do not unregister the distribution as part of this update. The Linux Install runtime… preference is not used on Windows.

Troubleshooting

Required feature is not installed

For HCS_E_SERVICE_NOT_AVAILABLE during runtime preparation, Windows could not create the WSL virtual machine. In administrator PowerShell:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart Windows. Check Task Manager / Performance / CPU for Virtualization: Enabled; if disabled, enable hardware virtualization in BIOS/UEFI. If Windows itself is a virtual machine, its host must expose nested virtualization. If the error persists, check the boot setting:

bcdedit /enum | findstr -i hypervisorlaunchtype

Only if it reports Off, enable it and restart:

bcdedit /set hypervisorlaunchtype Auto

See Microsoft’s WSL troubleshooting guide.

Cannot find wsl.exe

For spawn wsl.exe ENOENT, first check that wsl --version works in PowerShell. If it does, install the refreshed muSRFlow build: early rc.5 builds incorrectly replaced the Windows executable search path. Also check that the selected work directory exists and is writable.

Cannot load libCore.so

Install the refreshed muSRFlow build. It passes the ROOT library directory inside WSL for every bundled command. Setting a Windows ROOTSYS or LD_LIBRARY_PATH is not a substitute for this launcher fix.

Missing boost/version.hpp or plotting crash

Follow Existing installations to install boost-devel in an older runtime. The corrected runtime includes it. If plotting still crashes, include the full command output when reporting the problem.

No spectrum window appears

Confirm that wsl --version lists WSLg, update WSL, and inspect the muSRFlow run log. Successful runtime import or a successful fit alone does not verify interactive graphics support.

Reporting a problem

Include the muSRFlow version, full run log, and the output of:

wsl --version
wsl --status
wsl --list --verbose

The corrected runtime has completed a real fit and generated a PNG in a Linux container. Interactive Windows/WSLg plotting still needs validation on the target PC.