Understanding Python sys.flags for Runtime Options

Python's sys.flags struct sequence provides programmatic, read-only access to the command-line flags and runtime environment variables passed to the interpreter upon startup. This article explains how sys.flags works, breaks down the key interpreter options it exposes, and demonstrates how to inspect these runtime configurations inside your Python scripts.

What Is sys.flags?

When the Python interpreter initializes, it parses command-line arguments (such as -O, -v, or -B) and runtime environment variables (such as PYTHONOPTIMIZE or PYTHONDONTWRITEBYTECODE). The resulting state of these interpreter configurations is stored in sys.flags, which is an instance of a read-only structseq (a named tuple-like object) defined in the standard sys module.

Each attribute in sys.flags corresponds to a specific flag or setting. The attributes are integers, usually representing either a boolean state (0 for disabled, 1 for enabled) or an integer level representing how many times a flag was passed.

Accessing sys.flags

You can inspect the entire structure or access individual fields directly:

import sys

# View all flags and their current values
print(sys.flags)

# Access a specific flag
print("Optimization level:", sys.flags.optimize)
print("Bytecode suppression:", sys.flags.dont_write_bytecode)

If you start Python with python -O -B script.py, sys.flags.optimize will return 1, and sys.flags.dont_write_bytecode will return 1.

Common Attributes Exposed by sys.flags

Here are the primary attributes provided by sys.flags and what they reveal about the execution environment:

• optimize: Represents bytecode optimization levels set via -O or PYTHONOPTIMIZE. A value of 0 means standard execution, 1 removes assert statements (-O), and 2 removes both assert statements and docstrings (-OO).
• dont_write_bytecode: Set to 1 when -B or PYTHONDONTWRITEBYTECODE is active, indicating that Python will not write .pyc files to disk upon importing modules.
• verbose: Corresponds to the -v flag or PYTHONVERBOSE. It counts how many times -v was passed, signaling the level of verbosity for import statements and cleanup processes.
• interactive: Set to 1 when the -i flag is used, forcing an interactive prompt after running a script.
• inspect: Reflects the -i flag or PYTHONINSPECT, determining whether the interpreter enters interactive inspection mode on unhandled exceptions.
• debug: Set to 1 if Python was run with the -d flag or PYTHONDEBUG environment variable, enabling parser debugging output (requires a debug build of Python).
• no_user_site: Set to 1 when the -s flag or PYTHONNOUSERSITE prevents the user-site directory from being added to sys.path.
• no_site: Set to 1 when -S is used to disable the automatic import of the site module during initialization.
• ignore_environment: Set to 1 when -E is used, indicating that Python ignored all PYTHON* environment variables during startup.
• isolated: Set to 1 when the -I flag is passed, which enables isolated mode (combining -E and -s).
• bytes_warning: Reflects -b (value 1, issues warnings for implicit byte-string comparisons) or -bb (value 2, raises errors for implicit byte-string comparisons).
• quiet: Set to 1 when the -q flag is supplied, suppressing copyright and version banners in interactive sessions.
• dev_mode: Available in Python 3.7+, this boolean flag indicates whether the Python Development Mode (-X dev or PYTHONDEVMODE=1) is active.
• utf8_mode: Available in Python 3.7+, reveals whether UTF-8 mode (-X utf8 or PYTHONUTF8) is enabled (1), disabled (0), or set to explicit.

Practical Use Cases

Relying on sys.flags allows scripts and libraries to adapt dynamically to their execution environment:

1. Conditional Logic Based on Optimization: Library authors can verify if sys.flags.optimize == 2 before relying on __doc__ attributes at runtime, preventing errors caused by stripped docstrings.
2. Security and Isolation Audits: Diagnostic utilities can verify that sys.flags.isolated or sys.flags.ignore_environment is set to ensure reproducible and secure execution in production containers.
3. Debug Tooling: Developer tools can check sys.flags.dev_mode to automatically enable extra runtime checks and warnings without requiring separate configuration files.