Mypy Strict Kwargs

2026.1.12 · active · verified Thu Apr 16

mypy-strict-kwargs is a Mypy plugin that enforces the use of keyword arguments for function parameters that have default values, promoting clearer and less error-prone function calls. As of its current version, 2026.1.12, it follows a date-based release cadence with frequent updates, often several times a year.

Common errors

```
Plugin 'mypy_strict_kwargs.plugin' not found
```
cause The plugin is either not installed, or the path in `mypy.ini` is incorrect, or Mypy cannot locate the installed package.

fix First, ensure `mypy-strict-kwargs` is installed (`pip install mypy-strict-kwargs`). Verify the entry in `mypy.ini` is exactly `plugins = mypy_strict_kwargs.plugin` under the `[mypy]` section. Check your Python environment if Mypy is running in a different environment than where the plugin was installed.
```
error: Argument 'my_argument_name' must be passed as keyword argument
```
cause This is the intended error from the plugin, indicating you passed an argument with a default value positionally that should be passed as a keyword argument.

fix Modify your function call to explicitly pass the argument using its name, e.g., `my_function(value=10)` instead of `my_function(10)`.
```
ModuleNotFoundError: No module named 'mypy_strict_kwargs'
```
cause The `mypy-strict-kwargs` package is not installed in the Python environment where Mypy is being run.

fix Install the package using `pip install mypy-strict-kwargs`. Ensure you are installing into the correct Python environment if you are using virtual environments.

Warnings

gotcha The plugin explicitly ignores certain function types, including methods with `**kwargs`, `__init__` methods, and `@property` setters. This means these specific functions will not be checked for strict keyword argument usage.
Fix: Be aware of these exclusions. If strict keyword enforcement is needed for these cases, alternative Mypy checks or refactoring might be required.
breaking mypy-strict-kwargs requires Python 3.10 or newer. Installing or running with older Python versions will lead to compatibility errors.
Fix: Ensure your development environment and Mypy execution environment are using Python 3.10 or higher. Upgrade Python if necessary.
gotcha The plugin must be explicitly enabled in your `mypy.ini` (or equivalent Mypy config). Simply installing the package is not enough; Mypy will not use it unless specified in the configuration file.
Fix: Add `plugins = mypy_strict_kwargs.plugin` under the `[mypy]` section in your Mypy configuration file (`mypy.ini`, `pyproject.toml`, etc.).
gotcha The plugin specifically targets arguments that have default values and can theoretically be passed positionally. It does not enforce keyword-only arguments for all parameters, nor does it enforce keyword-only arguments for parameters already marked as keyword-only using `*`.
Fix: Understand that the plugin's scope is for arguments with defaults. For strict keyword-only enforcement on arguments without defaults, use `*, arg: type` in your function signature.

Install

pip install mypy-strict-kwargs Install Mypy Strict Kwargs

Imports

MypyStrictKwargsPlugin
wrong:
```
from mypy_strict_kwargs import plugin
```
correct:
```
[mypy]
plugins = mypy_strict_kwargs.plugin
```
mypy-strict-kwargs is a Mypy plugin, not a standard Python library to be imported in Python code. It must be enabled by adding `plugins = mypy_strict_kwargs.plugin` under the `[mypy]` section of your `mypy.ini` or equivalent Mypy configuration file. Importing it directly in Python will not activate the plugin's checks.

Quickstart

To use mypy-strict-kwargs, first install it, then enable the plugin in your `mypy.ini` configuration file. The plugin will then enforce that arguments with default values are passed as keyword arguments when a positional argument would suffice, ensuring clarity in function calls. Run `mypy main.py` to see the effect.

# mypy.ini
[mypy]
plugins = mypy_strict_kwargs.plugin

# main.py
def calculate(a: int, b: int, operation: str = "add") -> int:
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    else:
        raise ValueError("Invalid operation")

# These calls will pass Mypy checks
print(calculate(1, 2, operation="add"))
print(calculate(a=5, b=3))

# This call will trigger a Mypy strict-kwargs error:
# print(calculate(10, 5, "subtract"))
# To fix, pass 'operation' as a keyword argument:
print(calculate(10, 5, operation="subtract"))

view raw JSON →