PYTHONDONTWRITEBYTECODE stops Python writing .pyc files when it imports modules, and PYTHONUNBUFFERED makes output unbuffered so logs appear immediately. Both are set to any non-empty value, and both are common in Python Dockerfiles. Neither is a security control, but they help read only filesystems and incident logs.
What each setting does
The Python command line documentation defines them plainly.
PYTHONDONTWRITEBYTECODE: if set to a non-empty string, Python will not try to write .pyc files on the import of source modules. It is equivalent to the -B option.
PYTHONUNBUFFERED: if set to a non-empty string, it is equivalent to the -u option, which makes the standard streams unbuffered.
Put them in the image like this:
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1
Why they matter in a container
| Setting | Benefit | What it does not do |
|---|---|---|
| No bytecode writes | App can run with a read only filesystem without errors; no stray files in layers | Does not make imports faster, in fact slightly slower to start |
| Unbuffered output | Log lines reach stdout straight away, so a crash does not lose the last lines | Does not add structure or timestamps to logs |
The second point matters for incident work. If a process dies with buffered output, the last messages before the crash can be lost. For a security investigation those last lines are often the useful ones.
The bytecode trade-off
Skipping bytecode writes means Python has to compile your modules in memory at each start. For a long running service that cost is paid once per process and is small. For short lived jobs or serverless style startup, it can add up.
There is a middle route if startup matters. Compile bytecode at build time, so the .pyc files are baked into the image and read only at run time. Tools in the ecosystem expose this, for example the uv Docker guide documents a compile bytecode option for installs. Check the documentation of your installer for the exact flag.
Pairing with a read only root filesystem
If you run the container with a read only root filesystem, Python's attempt to write .pyc files into the application directory would fail quietly or noisily depending on the version and configuration. Setting the variable avoids relying on that behaviour. Give the app a small writable temp directory for anything else it needs. Our guide on read only root filesystems in Kubernetes covers the volume side.
Two related mistakes to avoid
- Copying a developer's local pycache directories into the image. Use a .dockerignore entry so they are left out.
- Assuming unbuffered output means logs are safe to share. Log content still needs review for personal data and tokens.
Where Safeguard fits
These settings reduce operational surprises. For supply chain risk, Safeguard scans Python dependencies, builds SBOMs and can gate pull requests on policy. Try the free scan to see which packages your service pulls in.
Quick check
Do these variables affect pip?
They configure the Python interpreter. Pip runs on Python, so the bytecode setting also applies to its imports, but they do not change what pip installs.
Is setting PYTHONUNBUFFERED to 1 required?
Any non-empty string works. Many Dockerfiles use 1 by convention.
Sources
Last reviewed: 19 October 2026.
