Home Free Download Manual Forum
Ctrl + K to search...
SumatraPDF documentation
/
Portable vs installer (and how `libmupdf.dll` is loaded)
md
This page explains how SumatraPDF’s portable and installable layouts work, what changed in 3.7, and why you sometimes see libmupdf.dll on disk even with a “single” executable.
See also Installation, Corrupted installation, and Failed to load libmupdf.

Before 3.7: two different product shapes #

Flavor What users got Layout
Installer Run an installer; files under Program Files or %LOCALAPPDATA% Multiple files on disk: SumatraPDF.exe, libmupdf.dll, and optional helpers such as PdfPreview.dll (Explorer preview) and the search filter (ifilter) DLL when registered
Portable Download a zip / single program One self-contained .exe — no separate libmupdf.dll next to the app for normal use
That meant two build/distribution artifacts: an installable multi-file executable and a portable single-file executable.

From 3.7: one executable is both installer and portable #

Starting with 3.7, the same SumatraPDF.exe binary can:
  • act as the installer (register associations, write files into an install directory, etc.), or
  • run as the application in portable or installed form.
Benefit: we only need to build and ship one executable for the main app (plus optional tools). Installer and portable are no longer two different executables.

Why libmupdf.dll still appears on disk #

MuPDF lives in libmupdf.dll, which is delay-loaded and also embedded inside the EXE (compressed resource). Windows can only load a normal DLL from a file path with LoadLibrary — not straight out of the EXE’s resources.
So for the unified single-EXE design to work, SumatraPDF must extract libmupdf.dll to disk at least once, then load it. That is the cost of merging portable and installer into one binary.
(Static-linked special builds that bake MuPDF into the EXE do not embed/extract libmupdf.dll; the public downloads use the DLL model.)

How we choose installer mode vs app mode #

Installer UI / install logic runs when any of these is true:
  1. Executable name contains install (case-insensitive), e.g.
    SumatraPDF-3.7-64-install.exe
    Official installers are named this way. Names containing uninstall are treated as uninstaller, not installer.
  2. Command-line flags that mean “install now”, notably -install (and related install flags such as fast/silent install variants documented under Installer cmd-line arguments).
So:
  • Renaming the file so the name includes -install (or downloading the official *-install.exe) → installer behavior.
  • Running without that name as a normal app → viewer mode (portable or already-installed layout).
  • You can force install with -install even if you renamed the EXE.
If the name looks like an installed app but libmupdf.dll next to the EXE is missing or the wrong size (does not match the copy embedded in this EXE), Sumatra may treat the layout as a corrupted installation and stop — see Corrupted installation. Use the installer, portable load path, or -x extract so EXE and DLL match.

Where libmupdf.dll is extracted / loaded #

On startup, SumatraPDF tries to load a DLL whose file size matches the embedded libmupdf.dll (avoids using a leftover DLL from another build).
Order of attempts (simplified):
  1. Next to the executable
    …\libmupdf.dll beside SumatraPDF.exe
    • Typical after a full install or after -x extract.
    • Load only (no extract) if the size already matches.
  2. Build-specific data directory under Local AppData (portable / single-exe path when the DLL is not already beside the EXE):
    %LOCALAPPDATA%\SumatraPDF-data\<build-id>\libmupdf.dll
    • <build-id> is a short hex id derived from a hash of this EXE (so different builds do not share one DLL).
    • Sumatra extracts the embedded DLL here if needed, then loads it.
    • Same tree is used for other non-settings data (logs, crash info, caches) for that build.
  3. Fallback: extract next to the EXE (if AppData is unusable) and load from there.
So:
Situation Typical libmupdf.dll location
Installed via installer / extracted with -x Same folder as SumatraPDF.exe
Portable / single-exe first run %LOCALAPPDATA%\SumatraPDF-data\<build-id>\
Settings still follow portable vs installed rules separately (settings next to the EXE when running portable; %LOCALAPPDATA%\SumatraPDF when installed) — see How we store settings. That is independent of where the MuPDF DLL is extracted.

Portable mode (settings / data next to the EXE) #

“Portable mode” for settings means: not considered an installed copy (not under Program Files / known install location). Then settings and some caches prefer the directory of the executable (if writable). That is separate from “single EXE that still extracts libmupdf.dll to AppData.”

Summary #

Topic Detail
Pre-3.7 Installer = multi-file (SumatraPDF.exe + libmupdf.dll + preview/ifilter DLLs as installed); portable = single self-contained EXE
3.7+ Same EXE is installer and app; MuPDF still needs a real libmupdf.dll file on disk
Installer trigger Name contains install (not uninstall), and/or -install (etc.)
DLL extract Embedded DLL → preferably next to EXE if already installed; else %LOCALAPPDATA%\SumatraPDF-data\<build-id>\
Why One binary to build and distribute; Windows requires loading DLL from disk
SumatraPDF documentation
/
Portable vs installer (and how `libmupdf.dll` is loaded)
md