Skip to main content
Mypy uses error codes to classify different types of errors. This allows you to enable or disable specific error checks and apply granular # type: ignore comments.

​
Error code structure

​
ErrorCode class

Each error code in Mypy is represented by an ErrorCode instance defined in mypy.errorcodes. 
class ErrorCode:
    def __init__(
        self,
        code: str,
        description: str,
        category: str,
        default_enabled: bool = True,
        sub_code_of: ErrorCode | None = None,
    ) -> None:
        self.code = code
        self.description = description
        self.category = category
        self.default_enabled = default_enabled
        self.sub_code_of = sub_code_of
​
code
str
required
The error code identifier (e.g., "attr-defined", "type-arg")
​
description
str
required
Human-readable description of what this error checks
​
category
str
required
Category of the error (currently always "General")
​
default_enabled
bool
default:"True"
Whether this error code is enabled by default
​
sub_code_of
ErrorCode | None
Parent error code if this is a more specific variant

​
Error code categories

Mypy’s error codes fall into several categories:

​
Type errors

Errors related to type incompatibilities and type checking:
  • attr-defined - Attribute existence checks
  • arg-type - Argument type mismatches
  • return-value - Return type mismatches
  • assignment - Assignment type mismatches
  • override - Method override compatibility
View all type error codes →

​
Syntax errors

Errors related to Python syntax:
  • syntax - Syntax errors in Python code
View syntax error codes →

​
Other errors

Import errors, definition errors, and other checks:
  • import-not-found - Missing imports
  • name-defined - Undefined names
  • no-redef - Duplicate definitions
View other error codes →

​
Using error codes

​
In type: ignore comments

Specify which errors to ignore: 
from typing import Any

x: int = "hello"  # type: ignore[assignment]
y: Any = some_func()  # type: ignore[no-any-return]

​
Enable/disable error codes

Use command-line flags or config file: 
# Enable specific error codes
mypy --enable-error-code=truthy-bool,unused-awaitable src/

# Disable specific error codes
mypy --disable-error-code=misc src/
In mypy.ini: 
[mypy]
enable_error_code = truthy-bool, unused-awaitable
disable_error_code = misc

​
Per-module configuration

[mypy]

[mypy-tests.*]
disable_error_code = no-untyped-def

​
Error code hierarchy

Some error codes have sub-codes for more specific cases: 
# Parent code
ASSIGNMENT = ErrorCode(
    "assignment",
    "Check that assigned value is compatible with target",
    "General"
)

# Sub-code
METHOD_ASSIGN = ErrorCode(
    "method-assign",
    "Check that assignment target is not a method",
    "General",
    sub_code_of=ASSIGNMENT,
)
When you ignore a parent code, all sub-codes are also ignored: 
# Ignores both assignment and method-assign
x.method = func  # type: ignore[assignment]

​
Default vs optional error codes

​
Enabled by default

Most error codes are enabled by default: 
ATTR_DEFINED = ErrorCode(
    "attr-defined",
    "Check that attribute exists",
    "General",
    default_enabled=True,  # Default
)

​
Disabled by default

Some stricter checks require opt-in: 
NO_UNTYPED_DEF = ErrorCode(
    "no-untyped-def",
    "Check that every function has an annotation",
    "General",
    default_enabled=False,
)
Enable with: 
mypy --disallow-untyped-defs  # Enables no-untyped-def
# or
mypy --enable-error-code=no-untyped-def

​
Accessing error codes programmatically

​
Get all error codes

from mypy.errorcodes import error_codes

for code_name, error_code in error_codes.items():
    print(f"{code_name}: {error_code.description}")

​
Check if a code is enabled

from mypy.errorcodes import ATTR_DEFINED
from mypy.options import Options

options = Options()
if ATTR_DEFINED not in options.disabled_error_codes:
    print("attr-defined is enabled")

​
Sub-code mapping

from mypy.errorcodes import sub_code_map, ASSIGNMENT

# Get all sub-codes of a parent
for sub_code in sub_code_map[ASSIGNMENT.code]:
    print(f"Sub-code of assignment: {sub_code}")
# Output: "Sub-code of assignment: method-assign"

​
Common error codes

Here are the most frequently encountered error codes:

attr-defined

Check that attributes exist on objects

name-defined

Check that names are defined before use

arg-type

Check argument types in function calls

return-value

Check return value matches function signature

assignment

Check assignment type compatibility

import-not-found

Check that imports can be resolved

​
Error code reference

​
All error codes list

Mypy defines over 60 error codes. They are documented in detail across these pages:

Type errors

Type checking error codes

Syntax errors

Syntax and parsing errors

Other errors

Import, definition, and other errors

​
Special error codes

​
misc

The catch-all error code for various uncategorized checks: 
MISC = ErrorCode("misc", "Miscellaneous other checks", "General")
Future Mypy versions will add more specific error codes to replace some misc errors.

​
syntax

Syntax errors are often blocking (cannot be ignored): 
SYNTAX = ErrorCode("syntax", "Report syntax errors", "General")

​
Best practices

​
Use specific error codes

# Good - specific
x = 1
y = "hello"
result = x + y  # type: ignore[operator]

# Avoid - too broad  
result = x + y  # type: ignore

​
Enable strict optional checks

[mypy]
enable_error_code = (
    truthy-bool,
    redundant-expr,
    unused-awaitable,
    ignore-without-code,
)

​
Document ignored errors

# type: ignore[attr-defined]  # TODO: Fix after API update
obj.new_attribute = value

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us