Why does a local file named logging.py shadow the standard library's logging module?

### The import system has no favourites `import logging` does not mean "load the standard library's logging package". It means "find the first thing on `sys.path` that can supply a top-level module named `logging`". The import machinery walks `sys.path` in order, asks each entry's finder whether it can provide that name, and stops at the first yes. The standard library directory sits somewhere in the middle of that list, so anything ahead of it wins outright. What sits ahead of it is the entry the interpreter prepends for you before your first line runs. Which entry that is depends on how the process was launched: - `python app.py` - the directory containing `app.py` (not necessarily the working directory). - `python -m pkg.mod` - the current working directory. - `python -c '...'`, a script piped on stdin, or the interactive prompt - an empty string, which the import system resolves as the current working directory. That single entry is the whole mechanism behind name shadowing. A `logging.py` sitting next to `app.py` is found before the standard library's `logging` package, and so is a `json.py`, a `types.py`, a `queue.py`, a `secrets.py`, a `select.py`, a `copy.py`, an `email.py` or the perennial `test.py`. ### Why the failure is confusing The symptom is usually not `ImportError`. Your file imports fine; it simply is not the module anyone wanted. So the failure surfaces later and elsewhere: - `AttributeError: module 'logging' has no attribute 'getLogger'`, raised from inside a dependency that imported the name for its own use, nowhere near your file. - A partially-initialized-module error, when your `logging.py` itself does `import logging` (directly or through another module) and re-enters a module that is still executing. - No error at all: your file is close enough that the program runs and silently loses behaviour. The one-line diagnosis is to print the module's origin - `import logging; print(logging.__file__)` - which names the offending file immediately. Printing `sys.path[0]` shows the prepended entry that let it in. ### The fixes, in order of preference **Rename the file.** Shadowing a standard-library name is a naming defect, not an interpreter defect, and no flag makes the name safe to keep. Nothing else in the list removes the problem for people who run your code some other way. **Start the interpreter with `-P`, or set `PYTHONSAFEPATH=1`.** Both landed in Python 3.11 and mean the same thing: do not prepend that potentially unsafe path at all. Under them `sys.path` simply lacks the script directory (or the working directory, or the empty string), so the standard library is reached first. `sys.flags.safe_path` is `1` when either is in effect, which lets a program assert its own launch conditions. **Use `-I` when you want the whole isolation package.** Isolated mode implies `-P` along with `-E` and `-s`, so it covers this case plus the environment and the per-user site directory. ### Three caveats worth carrying First, `-E` makes the interpreter ignore `PYTHON*` environment variables, and `PYTHONSAFEPATH` is one of them - so `-E` on its own actively disables the environment-variable form of the fix. If both matter, pass `-P` (or `-I`) on the command line, where it cannot be ignored. Second, `-P` is per process. A child you launch with `subprocess` inherits your environment but not your command-line flags, so an isolated parent can still spawn a shadowed child unless you pass the flag along. Third, `-P` with `-m` changes how you run code out of a checkout. Suppressing the working-directory entry is exactly what stops the shadowing, and it is also what makes `python -P -m mytool` fail when `mytool` exists only as a directory in the current folder. That is a signal to install the project (an editable install is the usual answer) rather than to relying on the working directory being importable. ### Two myths to retire Deleting the file does not repair a process that already imported it: the module object lives in `sys.modules` and other modules hold direct references to it, so only a restart (or a deliberate `importlib.reload` of everything involved) helps. And a leftover `__pycache__/logging.cpython-314.pyc` cannot keep shadowing after the source is gone. Since the cache-directory layout was introduced, a cached bytecode file inside `__pycache__` is only ever used alongside its source file; it is not importable on its own.