使用 mypy 对 Python 程序进行静态类型检查

叶初

发布时间：2026-10-15 | 3人浏览过

原创

mypy 是 Python 的静态类型检查器，能验证带有类型提示的代码，提前发现潜在错误。本文介绍 mypy 的安装方法、执行检查流程、忽略特定行的技巧，以及配置文件（如 mypy.ini）的查找顺序和常用配置项，帮助开发者提升代码可读性与可维护性。

前言

过去，我常认为 Python 的类型提示仅具装饰作用，即便类型标注错误或参数传递不符，程序依然能够运行。直到接触 mypy 这一工具后，我才意识到静态检查的实际价值。本文将详细介绍 mypy 的使用方法。

mypy 作为 Python 的静态类型检查器，允许开发者在运行代码前预先检查带有类型提示的代码。若存在类型错误，mypy 会给出明确提示，从而真正发挥类型提示的作用。在后续开发流程中，可强制要求 mypy 检查通过后方可上线，以此提升代码的可读性和可维护性。

这一功能非常实用。接下来，我们将具体探讨如何使用 mypy。

1、安装

安装过程十分简单，只需执行 pip install mypy 即可完成安装。

2、执行

假设存在一个名为 demo1.py 的 Python 程序，其内容如下：


def greeting(name: str) -> str: #这里提示有问题
    print (f'Hello { name }')

x: str = 'xxx' 
y: int = "yyy" #这里应该提示有问题
greeting(x) 
greeting(y) #这里应该提示有问题

代码中已标注出两处明显的错误，现在让我们使用 mypy 进行检查：

结果显示，mypy 成功识别出三处错误并逐一提示，功能十分强大。

若希望跳过对某一行代码的检查，可在该行注释中添加 "# type: ignore"：


y: int = "yyy" # type: ignore

mypy 拥有强大且易用的类型系统，具备类型推断、泛型、可调用类型、元组类型、联合类型以及结构子类型等优秀特性。

3、常用的内置类型

4、配置文件

mypy 会按顺序在当前目录下查找配置文件，优先级如下：

mypy.ini

.mypy.ini

pyproject.toml

setup.cfg

若上述文件均未找到，mypy 将继续在以下路径中依次查找配置文件：

$XDG_CONFIG_HOME/mypy/config

~/.config/mypy/config

~/.mypy.ini

此外，你也可以使用--config-file 参数来指定特定的配置文件。

一个典型的 mypy.ini 配置文件示例如下：


# Global options:

[mypy]
python_version = 3.7
warn_return_any = True
warn_unused_configs = True

# Per-module options:

[mypy-mycode.foo.*]
disallow_untyped_defs = True

[mypy-mycode.bar]
warn_return_any = False

[mypy-somelibrary]
ignore_missing_imports = True

关于配置文件的详细说明，请参阅官方文档：https://mypy.readthedocs.io/en/stable/

以下是常见配置项的说明：

files：逗号分隔的路径列表，若命令行未指定检查目标，则默认检查这些路径，支持递归查找。

exclude：指定应忽略检查的文件名、目录名或路径。

ignore_missing_imports：禁止显示关于无法解析的导入模块的错误消息。

disallow_untyped_defs：禁止定义缺少类型注释或类型注释不完整的函数。

plugins：逗号分隔的 mypy 插件列表。