# Fixing PyInstaller --onefile tmpfs Issues by Switching to --onedir and Clarifying Size Myths

> Source: <https://dev.to/romdevin/fixing-pyinstaller-onefile-tmpfs-issues-by-switching-to-onedir-and-clarifying-size-myths-3bpn>
> Published: 2026-11-21 06:25:26+00:00

**Recommendation:** Use --onedir instead of --onefile when deploying to containers or hosts with small tmpfs /tmp or /dev/shm mounts, since --onefile re-extracts the entire payload there on each start.
More in the playbook "Running AI in production": <https://wpnews.pro/playbooks/production-ops>

When you pass `--onefile` to PyInstaller, the build tool does not strip dead code, prune unused shared libraries, or shrink your Python interpreter. Instead, the bootloader appends a compressed archive (typically using zlib or LZMA) containing the exact same set of `.pyc` bytecode files, `.so`/`.dll` shared objects, and data assets that a `--onedir` build places into a directory tree. If your bundle contains a 600 MB scientific or machine learning stack, `--onefile` still carries all 600 MB of underlying payload inside that single executable. Any file-size reduction you observe on disk comes from archive compression ratios minus a small bootloader stub, whereas at runtime the uncompressed bytes must be written out anyway—meaning `--onefile` often inflates temporary storage pressure rather than saving space.

The physical cause of `tmpfs` failures lies in how a `--onefile` binary boots. When launched, the C bootloader reads the embedded archive, decompresses each entry, and writes the unpacked files into a temporary directory—commonly under `/tmp` or `TMPDIR`—before loading the embedded Python runtime from those extracted files. Because `tmpfs` stores files in page cache backed by system RAM and swap rather than a persistent block device, every decompressed byte occupies volatile memory pages or hits a strict `tmpfs` size cap (such as a container's default 64 MB `/dev/shm` or tight `/tmp` mount). As decompressed bytes accumulate in `tmpfs`, free memory pages shrink or the mount hits its quota; once exhausted, the write syscall fails with `ENOSPC` (no space left on device) or the kernel's out-of-memory (OOM) killer terminates the process.

Startup latency follows a parallel mechanical chain. Under `--onefile`, cold start requires sequential decompression and filesystem writes of potentially hundreds of megabytes into the temporary directory on every invocation, followed by dynamic linker symbol resolution and Python imports. Under `--onedir`, the files already sit unpacked on disk or in an existing directory, so launching skips the full-bundle decompression-and-extraction pass and goes straight to loading shared libraries and executing Python code. However, `--onedir` is not universally faster: if a network filesystem has high metadata latency across thousands of small files, or if a warm `tmpfs` page cache already holds the extracted payload while cold storage is slow, those local I/O dynamics can shift the balance.

`--onedir`.` ENOSPC` quota exhaustion and avoids duplicating payload bytes across both archive/page cache and extracted files in RAM-backed `tmpfs`. It is strictly more reliable than `--onefile` when temporary space is bounded or memory is tight.`TMPDIR` at a larger `/tmp` or When a PyInstaller **--onefile** executable launches, a compiled C bootloader opens its own binary image, locates the trailing archive appended during build, decompresses entries (typically zlib or LZMA), and writes every extracted file into a temporary directory under *TMPDIR* or */tmp* before starting the embedded Python runtime. When that target directory sits on a **tmpfs** mount, those writes do not hit a disk block layer; they allocate kernel page cache backed by physical RAM and swap. Switching to **--onedir** eliminates this runtime extraction phase because the bootloader loads pre-unpacked *.pyc* bytecode, shared libraries, and data files directly from disk rather than materializing a second copy in volatile memory.

A common assumption is that **--onefile** shrinks an application because it produces a single file. It does not prune unused modules, strip dead bytecode, or shrink shared libraries; it packages the same dependency graph as **--onedir** inside a compressed container plus a bootloader stub. Any file-size reduction comes strictly from archive compression minus bootloader overhead, while runtime execution still inflates the uncompressed payload.

| **Deployment Scenario** | **Physical Constraint** | **Causal Failure Chain** | **Observable Effect** | 
| **Restricted container /tmp** | Capped *tmpfs* on*/tmp* with tight container memory limit | Bootloader decompresses bundle into */tmp* -> page cache fills capped*tmpfs* or pushes cgroup memory to limit ->*write* returns*ENOSPC* or cgroup OOM kills task | Immediate startup crash with extraction write error or silent exit code 137 | 
| **Shared-memory /tmp mapped to /dev/shm** | */tmp* symlinked or bound to small*/dev/shm* segment | Unpacked shared libraries and data exceed small shared-memory cap -> page allocation hits segment ceiling -> archive unpack halts mid-stream | Partial temp folder and failed PyInstaller bootloader extraction error | 
| **Hardened Linux runtime with noexec /tmp** | *tmpfs* mounted with*noexec* (and sometimes*nosuid* /*nodev* ) | Bootloader writes *.so* or binary payloads to*/tmp* ->*dlopen* or*execve* hits*noexec* mount flag -> kernel blocks code execution | Dynamic linker or permission/execution failure during runtime initialization | 
| **High-concurrency worker autoscaling** | Multiple **--onefile** workers starting simultaneously on one host | Concurrent processes decompress duplicate bundles into *tmpfs* -> multiplied page-cache footprint and CPU decompression contention -> memory exhausts host RAM/swap | Cascading OOM kills and multi-second startup spikes across workers | 
| **Low-RAM embedded or edge Linux node** | Limited physical RAM with little or no swap | Decompressed payload plus Python/ML runtime heap exceeds physical page frames -> memory reclaim cannot free pinned/active pages -> kernel OOM killer triggers | Process killed mid-import or right after extraction completes | 

**--onedir** is the optimal default for server, container, and edge deployments. By keeping files unpacked in a directory, it removes per-launch decompression work, avoids duplicate byte materialization inside *tmpfs*, and makes memory consumption much more predictable. It also matches actual on-disk payload reality: a 600 MB scientific or AI stack is roughly 600 MB of actual code, libraries, and data either way, so **--onefile** is trading startup time and runtime memory/temp overhead for single-file convenience rather than shrinking the real application footprint.

Even **--onedir** stops working cleanly under specific edge conditions. If a distribution pipeline strictly mandates a single standalone binary with zero supporting directories or wrapper scripts, **--onedir** does not meet that packaging constraint. In addition, when a **--onedir** bundle containing thousands of small files sits on a high-metadata-latency network filesystem without pre-staging, repeated *open* and *stat* round-trips across many tiny files can slow startup, whereas a warm *tmpfs* page cache or slow cold storage can invert relative I/O costs between the two modes.

**Decision rule:** If */tmp* or *TMPDIR* is backed by a memory-capped *tmpfs*, or if cold-start speed and predictable RAM headroom matter more than a single file, use **--onedir**; use **--onefile** only when a hard single-file requirement applies and temp storage plus RAM/swap have enough headroom for full per-launch extraction.

When a Python service or CLI tool built with PyInstaller **--onefile** starts failing inside containers, restricted Linux pods, or low-memory nodes, the culprit is almost always how the bootloader handles temporary storage on **tmpfs**. Switching from **--onefile** to **--onedir** is the right fix in most server and container environments. It eliminates per-launch extraction onto memory-backed temporary filesystems, cuts cold-start overhead, and preserves predictable memory headroom without actually costing you real-world application size.

A common misconception is that **--onefile** shrinks your application. It does not prune unused imports, strip dead bytecode, or drop shared libraries from your dependency graph. It takes the exact same set of *.pyc* files, *.so* or *.dll* shared objects, and data files that **--onedir** places into a folder, compresses them into a trailing archive (typically zlib or LZMA), and attaches a C bootloader stub. If your scientific or AI stack unpacks to 600 MB, all 600 MB of underlying code and libraries still exist inside the single binary. The single executable looks smaller on disk only because the archive is compressed minus the bootloader stub's bytes; the moment it runs, those compressed bytes must be decompressed and written back out in uncompressed form.

Unlike a persistent block device such as an ext4 or XFS disk partition, **tmpfs** stores files in volatile page cache backed by physical RAM and swap. When a **--onefile** binary launches, its C bootloader reads its own trailing archive, decompresses entries in sequence, and writes the unpacked files into a temporary directory under *TMPDIR* or */tmp* before starting the embedded Python runtime.

Choosing between **--onedir** and **--onefile** is an operational trade-off between single-artifact convenience and runtime determinism. Once unpacked, both modes load shared objects and execute Python bytecode in the same general runtime model, but **--onefile** pays an extraction tax on every cold start while competing for **tmpfs** memory.

**--onedir** is not immune to environmental bottlenecks. If you place a large **--onedir** bundle containing thousands of small *.pyc* and dependency files onto a high-metadata-latency network filesystem (such as certain remote NFS or shared mounts) without pre-staging locally, repeated *open* and *stat* calls during Python startup can introduce noticeable latency—sometimes enough to invert the usual startup advantage over a warm **tmpfs** cache. It also falls short whenever a distribution policy strictly forbids a directory bundle or wrapper script.

Engineers running into **--onefile** **tmpfs** errors frequently make three mechanical mistakes: treating **--onefile** as if it shrinks runtime memory or dependency size; enlarging a **tmpfs** *TMPDIR* limit without adding backing RAM or swap (which simply shifts failures from *ENOSPC* to OOM kills); or pointing *TMPDIR* to another **tmpfs** path without checking whether *noexec* is set.

**If */tmp* or *TMPDIR* sits on a memory-capped tmpfs, or if cold-start speed and predictable RAM headroom matter more than shipping a single file, use --onedir. Use --onefile only when a strict single-file requirement applies and the target host has enough temporary storage, non-noexec permissions, and RAM/swap headroom to absorb full decompression on every launch.**

When a PyInstaller **--onefile** binary fails on **tmpfs**, the failure is not a quirk of PyInstaller being picky about temporary folders—it is a resource collision between archive decompression and memory-backed filesystem allocation. Switching to **--onedir** is the right move for servers, containers, and edge runtimes because it eliminates per-launch self-extraction, keeps memory consumption predictable, and exposes the true uncompressed size of your application rather than hiding it behind a zip or LZMA wrapper.

A common myth is that **--onefile** shrinks the application. It does not prune unused imports, strip dead bytecode, or drop heavy scientific or AI libraries from the dependency graph. It packs the exact same **.pyc** files, shared libraries (**.so** or **.dll**), and data assets into a compressed archive appended to a C bootloader stub. On disk, the single binary looks smaller only because archive compression (such as zlib or LZMA) squeezes repetitive bytes minus the bootloader overhead. At runtime, the bootloader still decompresses that payload and writes the full unpacked tree to disk before embedded Python starts. A 600 MB scientific or numerical stack is still 600 MB of code and libraries once materialized.

Unlike a persistent block device such as **ext4** or **XFS**, **tmpfs** stores files in volatile kernel page cache backed by physical RAM and swap. When a **--onefile** process launches, its C bootloader reads the trailing archive, decompresses entries sequentially, and issues **write** syscalls into **TMPDIR** (often **/tmp**) before Python imports begin. Each causal failure chain traces directly to that extraction step:

Between the two modes, **--onedir** is the superior default whenever you control the runtime environment, care about cold-start speed, or run inside memory-constrained containers and edge nodes. It places pre-unpacked files in an explicit directory (such as **/opt/app**) with deterministic ownership and permissions, avoiding **tmpfs** bloat and **/tmp** **noexec** traps.

**--onedir** stops working cleanly under two clear conditions: first, when distribution policy or packaging rules strictly require a single standalone executable with no supporting directory or wrapper; second, when a bundle containing thousands of small files is placed directly on a high-latency network filesystem (such as remote NFS) without local staging, where thousands of **open** and **stat** round-trips can make startup slower than unpacking into a warm local cache.

Engineers frequently make three avoidable mistakes when troubleshooting **--onefile** tmpfs failures. First, they assume **--onefile** reduces runtime RAM or trims unused dependencies, ignoring that unpacked artifacts still enter memory or page cache. Second, they enlarge the **tmpfs** size cap without adding backing RAM or swap, which merely trades an **ENOSPC** write error for an OOM kill when memory fills. Third, they point **TMPDIR** at another **tmpfs** mount without checking whether **noexec** is set, leaving **dlopen** and **execve** blocked.

**Selection rule:** If **/tmp** or **TMPDIR** sits on a memory-capped **tmpfs**, or if cold-start latency, predictable cgroup memory headroom, and explicit file permissions matter most, use **--onedir**. Use **--onefile** only when a strict single-file requirement applies and the target host provides enough temporary storage, non-**noexec** permissions, and RAM-plus-swap headroom for full decompression on every launch.

If **--onefile** must stay in place temporarily, contain the blast radius by setting **TMPDIR** to a non-**noexec** persistent or local scratch path with verified free space, sizing RAM and swap above peak unpacked payload plus runtime heap, and staging concurrent worker starts rather than launching dozens in lockstep.
