PY-IMPO0003 · unused_import

Report an unused import binding.

This is a deterministic rule for python. Read its implementation.

Definition

Report one resolved import binding that nothing in its own module reads. A read is counted wherever the interpreter would perform one, so a name tested by an elif, named as the type an except catches, matched by a case, deleted, used as a decorator, or spelled inside a string in a type expression is read exactly as much as a name a call passes. That is the complete boundary.

Three statements are never judged. A __future__ import is a compiler directive that binds nothing a reader was ever meant to use. A wildcard import binds names this reader cannot enumerate, so its disuse is unprovable rather than proven. An import written inside a try that states what to do when an import fails is there for whether it succeeds.

Evidence

The finding names the binding, the module it came from, and the exact line that states it, beside how many references resolved to it, which is the zero the rule turned on. The removal arrives from the fix this rule already declares rather than from a second statement of the same edit.

Exceptions

Keep imports that form an explicit public re-export, register behavior with a framework, or intentionally execute a documented module side effect. A name a module lists in __all__ is re-exported however that list is built, and so is a name an import restates as its own alias.

A string inside a subscript is read as the name it spells, since that is where a forward reference lives, so a mapping key matching an import silences this rule for that import. Reading it the other way would report a live forward reference and offer to delete it, which is the failure worth avoiding.

Examples

Bad

import json

Good

from __future__ import annotations
from .api import Client as Client
from .transports import *

try:
    import h2
except ImportError:
    raise ImportError("install the http2 extra") from None

References

• Generalizes Pylint W0611 unused-import
• Generalizes Ruff F401 unused-import
• Cites “Pyflakes”, unused import analysis
• Cites “The Python Language Reference”, the import system