cd /news/developer-tools/fixing-pyinstaller-onefile-tmpfs-iss… · home › topics › developer-tools › article
[ARTICLE · art-173672] src=dev.to ↗ pub= topic=developer-tools verified=true sentiment=· neutral

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

A developer documented why PyInstaller's --onefile mode fails on tmpfs mounts: the C bootloader decompresses the embedded archive and writes every extracted file into TMPDIR or /tmp on each launch, so on RAM-backed tmpfs those bytes consume page cache and can trigger ENOSPC or the OOM killer. The writeup argues --onefile does not shrink payloads—it packages the same .pyc, shared libraries and data as --onedir inside a compressed archive plus a stub—and recommends --onedir to skip runtime extraction when temporary space is bounded.

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 playbook: Running AI in production
by read10 min views2 publishedNov 21, 2026

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 boot 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 boot 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 boot reads the embedded archive, decompresses each entry, and writes the unpacked files into a temporary directory—commonly under /tmp or TMPDIR—before 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 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 boot 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 boot 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 boot stub. Any file-size reduction comes strictly from archive compression minus boot 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 | Boot decompresses bundle into /tmp -> page cache fills cappedtmpfs or pushes cgroup memory to limit ->write returnsENOSPC 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 boot extraction error | | Hardened Linux runtime with noexec /tmp | tmpfs mounted withnoexec (and sometimesnosuid /nodev ) | Boot writes .so or binary payloads to*/tmp* ->dlopen orexecve hitsnoexec 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 boot 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 boot 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 boot 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 boot 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 boot stub. On disk, the single binary looks smaller only because archive compression (such as zlib or LZMA) squeezes repetitive bytes minus the boot overhead. At runtime, the boot 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 boot 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.

── more in #developer-tools 4 stories · sorted by recency
── more on @pyinstaller 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/fixing-pyinstaller-o…] indexed:0 read:10min 2026-11-21 · —