What does Python's -O flag actually do to assert statements and __debug__?

`-O` is Python's oldest and most misunderstood command-line flag. The name is borrowed from C compilers, but it delivers none of what they deliver: no inlining, no loop unrolling, no native code generation. It removes two specific things from the bytecode, and it does so **when the code object is compiled**, not while it runs. ## 1. `assert` statements are not emitted Written out, `assert expr, msg` means roughly "if `__debug__` is true and `expr` is falsy, raise `AssertionError(msg)`". At optimization level 1 or higher the compiler emits *nothing* for that statement — there is no test, no jump, no exception construction in the resulting code object. This is not the same as raising and catching `AssertionError`, and it is not a runtime toggle: by the time the module is executing, the statement is simply not there. ## 2. `__debug__` becomes `False`, and its blocks are dropped `__debug__` is a compile-time constant rather than an ordinary global. The compiler inlines its value directly, so `if __debug__:` becomes `if False:` and the surrounding block is removed as unreachable code. That is why you cannot flip it yourself: ```python __debug__ = False # SyntaxError: cannot assign to __debug__ ``` The guard is useful for the expensive checks you would not want in production at all — validating a whole batch, recomputing a hash to compare it, building a debug string — because at level 1 they cost literally nothing. ## What `-O` does *not* do * It does not remove docstrings. That is level 2 (`-OO`). * It does not remove comments; comments never reach bytecode in the first place. * It does not remove annotations, type hints or any runtime type behaviour. * It does not make ordinary code faster. The only work saved is the work of the checks it deleted. Treating `-O` as a performance flag is the single most common wrong answer to this question. ## How the level is set and read back The level comes from the command line (`-O` is level 1, `-OO` is level 2) or from the `PYTHONOPTIMIZE` environment variable, which carries the level as an integer. Code reads it back through `sys.flags.optimize`, or infers level >= 1 from `__debug__` being `False`. The level applies to the whole process, including every module imported into it, and cached bytecode files are tagged with it (`opt-1`, `opt-2`) so caches built at different levels never overwrite each other. ```pycon >>> import sys >>> sys.flags.optimize, __debug__ (0, True) ``` Run the same two lines under `-O` and you get `(1, False)`. ## The part interviewers are really probing Because the statement disappears, **every side effect inside it disappears with it**. A line like `assert queue.pop() is not None` does the popping only when assertions are enabled; under `-O` the queue is never touched and the program silently takes a different path. The same trap catches `assert log_and_check(row)` and any assert whose expression mutates state. That leads to the rule: `assert` states an invariant that is true whenever the program is correct, and its job is to fail loudly during development. A condition that must hold no matter how the interpreter was started is not an assertion — it needs an ordinary `if` and a real exception, or an explicit check that runs unconditionally. One more sharp edge lives in the syntax. `assert (cond, "message")` asserts a two-element tuple, which is always truthy, so the check never fires; the compiler emits a `SyntaxWarning` for exactly this mistake. Write `assert cond, "message"` with no parentheses around the pair. ## Is it worth using? Honest answer: rarely on its own merits. The saving is the cost of checks that were usually cheap, and the risk is that production runs code you never tested. The defensible uses are a genuinely expensive `if __debug__:` guard you want compiled out, or a deployment standard that everything — CI included — runs at the same level. What you should never do is turn it on in production for speed, since there is none to gain, while the behaviour of every assert in every dependency changes underneath you.