python/cpython · error

'import warnings' failed; traceback:\n

Error message

'import warnings' failed; traceback:\n

What it means

Printed during init_interp_main (Python/pylifecycle.c) when sys.warnoptions is non-empty and PyImport_ImportModule("warnings") returns NULL. The interpreter proceeds anyway (the exception is printed with _PyErr_Print), but warning filters configured via -W / PYTHONWARNINGS are then inert because the warnings machinery never loaded.

Source

Thrown at Python/pylifecycle.c:1480

#endif

    status = add_main_module(interp);
    if (_PyStatus_EXCEPTION(status)) {
        return status;
    }

    if (is_main_interp) {
        /* Initialize warnings. */
        PyObject *warnoptions;
        if (PySys_GetOptionalAttrString("warnoptions", &warnoptions) < 0) {
            return _PyStatus_ERR("can't initialize warnings");
        }
        if (warnoptions != NULL && PyList_Check(warnoptions) &&
            PyList_Size(warnoptions) > 0)
        {
            PyObject *warnings_module = PyImport_ImportModule("warnings");
            if (warnings_module == NULL) {
                fprintf(stderr, "'import warnings' failed; traceback:\n");
                _PyErr_Print(tstate);
            }
            Py_XDECREF(warnings_module);
        }
        Py_XDECREF(warnoptions);
    }

    if (config->site_import) {
        status = init_import_site();
        if (_PyStatus_EXCEPTION(status)) {
            return status;
        }
    }

    // Initialize lazy imports based on configuration. Do this after site
    // module is imported to avoid circular imports during startup.
    if (config->lazy_imports == 0) {
        return _PyStatus_ERR("PyConfig.lazy_imports=0 is not supported");

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Read the traceback printed right after the message — it names the real import failure
2. Verify PYTHONHOME/PYTHONPATH and the interpreter's prefix (`python -c 'import sys; print(sys.prefix)'`)
3. Remove or rename local files that shadow stdlib modules (warnings.py, os.py, etc.)

Example fix

# before
$ ls
warnings.py
$ python -W error app.py
# after (rename the shadowing file)
$ mv warnings.py my_warnings.py
$ python -W error app.py

# smoke-test a healthy stdlib before enabling warning filters
python -c 'import warnings, os, sys; print(sys.prefix)' && python -W error app.py

When it happens

Trigger: Passing -W option(s) or PYTHONWARNINGS while the 'warnings' module cannot be imported: broken stdlib path (PYTHONHOME/PYTHONPATH misconfiguration), truncated or corrupt installation, a warnings.py shadowed by a local file, or MemoryError during import.

Common situations: Virtualenvs/containers with a half-copied stdlib; PYTHONHOME pointing at the wrong prefix; a project file named warnings.py earlier on sys.path; embedded interpreters with an incomplete sys.path.

Related errors

• pre-site failed:\n
• Cannot exit %r without entering first
• Expected an object of type str for 'message', not {type(mess
• {cls.__name__}() takes no arguments
• @deprecated decorator with non-None category must be applied

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/18ded2273873ae82. Report an issue: GitHub.