Installation

Install pysrim2 with uv or pip. Python 3.11 or newer is required. The import name is srim.

pysrim2 has two parts that are installed separately, and most users want both: the library (import srim, used in your own Python code) and the command line (pysrim2 install, which sets up SRIM itself).

The library, depending on how you work:

uv add pysrim2                                   # in a uv project
uv venv && source .venv/bin/activate && uv pip install pysrim2   # uv venv
python -m venv .venv && source .venv/bin/activate && pip install pysrim2   # pip venv
uv run --with pysrim2 my_simulation.py           # one-off script, nothing installed

The command line (it does not make import srim available to your own Python):

uv tool install pysrim2 && pysrim2 install

If the original pysrim is installed, remove it first, because both packages provide the srim module: uv remove pysrim && uv add pysrim2 in a uv project, uv pip uninstall pysrim && uv pip install pysrim2 in a uv venv, or pip uninstall pysrim && pip install pysrim2 with pip.

SRIM licence

SRIM © SRIM.com (James F. Ziegler) — free for non-commercial use only; see LEGAL.rtf. pysrim2 never ships SRIM; the installer downloads it and keeps Ziegler’s LEGAL.rtf next to every copy. Commercial users must get SRIM from srim.org themselves. You do not need SRIM if you only analyse existing output files.

Quick start

uv tool install pysrim2       # the pysrim2 command; or: pip install pysrim2
pysrim2 install --dry-run     # show every step and the exact commands, change nothing
pysrim2 install               # do it
pysrim2 doctor                # check the result

With no component names, pysrim2 install picks the right set for your platform (see below) and also installs the agent skill. Steps that need administrator rights ask for confirmation first (or run with --yes); --dry-run never changes anything. See Command line for all options and exit codes.

Windows (native)

pysrim2 install runs two steps: srim downloads SRIM-2013 into %LOCALAPPDATA%\pysrim2\srim, and vb5 puts the Visual Basic 5 runtime and the OCX controls TRIM needs next to it. Registering the OCX controls (regsvr32) needs administrator rights. pysrim2 does not elevate by itself: run pysrim2 install vb5 from an elevated (Administrator) terminal. The confirmation prompt (or --yes) is not a UAC prompt.

Linux (native, through wine)

The default set is wine, srim and skill. The wine step is two parts:

  1. wine packages. It installs wine with 32-bit support, xvfb-run, cabextract, unzip and curl through your package manager (apt, dnf, zypper or pacman; Fedora and Arch are untested). This needs sudo and asks first. On other distributions install them yourself, see the WineHQ download page.

  2. private wine prefix. A 32-bit prefix under ~/.local/share/pysrim2/wine with the VB5 runtime and OCX controls. pysrim2 never touches ~/.wine and ignores $WINEPREFIX; the prefix variable is only set in the environment of the child processes it starts.

SRIM runs headless through xvfb-run on a 1024x768x24 virtual screen, so no display is needed.

macOS

Native SRIM is not supported on macOS. Use the Container; running pysrim2 install uses Docker if it is already running (with the seccomp profile on Docker 29 and newer, see Container). If there is no container runtime it installs Podman, starts a Podman machine and pulls the image. It never installs Docker Desktop, which needs a paid subscription for larger organisations and a GUI installation with administrator rights.

Desktop app

The optional desktop app (pysrim2 app) guides the SRIM setup in a window. It needs the app extra (PySide6, matplotlib, the notebook tools marimo and JupyterLab, and nbconvert for the notebook PDF export; PySide6 alone is a download of over 100 MB, so the app is not part of the default install). Install it into the pysrim2 you already use with pysrim2 install app, which needs no administrator rights and also downloads the Chromium that the PDF export prints with, then start the app with pysrim2 app. See Desktop app for the setup, the status bar and the settings.

Where things live

pysrim2 keeps its files in one data directory: %LOCALAPPDATA%\pysrim2 on Windows, ~/Library/Application Support/pysrim2 on macOS and ${XDG_DATA_HOME:-~/.local/share}/pysrim2 elsewhere. These environment variables override the defaults:

PYSRIM2_HOME

The data directory.

PYSRIM2_SRIM_DIR

The directory holding TRIM.exe. If unset, pysrim2 uses <data directory>/srim, then an existing /tmp/srim.

PYSRIM2_WINEPREFIX

The private wine prefix (default <data directory>/wine).

TRIM().run() and SR().run() use this SRIM directory when you do not pass one. Runs happen in private copies of this directory (see srim.rundir.RunDir); the installed directory is not written to.

Installing SRIM by hand

If you prefer, extract SRIM yourself into any directory that contains TRIM.exe and point PYSRIM2_SRIM_DIR (or the srim_directory argument of run()) at it. pysrim2 never writes into such a directory. The archive pysrim2 installs is the srim-2013 release (srim.2013.zip, SHA-256 f425c4715d5a849c1f521a8fc14aff58d41066fa4ca773546690a220ff3acecf, with LEGAL.rtf and SRIM-NOTICE.txt as separate assets). A checksum mismatch is a hard error and nothing is installed. On Linux you still need the wine packages and prefix: pysrim2 install wine.

Troubleshooting

Start with pysrim2 doctor: every failing check has a fix: line.

The install seems stuck. Long sub-steps print a progress line when they start (creating the wine prefix, winetricks, the VB5 runtime, the SRIM download); the last line tells you where it is. Wine setup is bounded: a wineserver that does not exit within 60 s is stopped. Press Ctrl-C to abort; the private prefix’s wine processes are stopped.

An old winetricks. pysrim2 always downloads and uses its own pinned, checksum-verified winetricks and ignores any winetricks on your PATH (old copies do not know the OCX verbs it needs).

Mono, Gecko and controller drivers. They are disabled for the private prefix (the Wine Mono/Gecko prompts and the USB, controller and Bluetooth drivers can hang or crash headless setups). SRIM does not use them.

“X connection to :N broken” and Mesa/EGL warnings. Harmless; pysrim2 filters them from TRIM.run() and SR.run() output.

A run fails. SRIMProcessError carries SRIM’s stderr; SRIMRunError means SRIM wrote no result (old output is deleted before each run, so a crash never returns a previous run’s data).