py-wechat-ocr

这是一个基于微信 OCR 引擎（WeChatOCR）的 Python 封装库。它通过直接加载微信解包后的 wxocr.dll 结合底层的 CPython 扩展模块 wcocr.pyd（该二进制模块编译自 swigger/wechat-ocr 开源项目），实现极速、高准确率的本地图片文字识别（OCR）。

注意： 本库底层依赖编译好的 Windows 动态链接库，因此仅支持 Windows 平台。

环境要求

• 操作系统：Windows 10/11
• Python 版本：>= 3.10
• 已测试微信版本：微信 4.1.9.57 版本测试通过
• 本地依赖：电脑中已安装微信客户端（本库会自动从微信安装路径提取并解压核心的 OCR 依赖 WeChatOcr.bin）

安装方法

通过 PyPI 快速安装（推荐）

您可以直接使用 pip 或 uv 进行一键安装：

pip install py-wechat-ocr
# 或者使用 uv 安装
uv add py-wechat-ocr

本地源码编译安装

1. 在项目根目录下构建包：

   uv build
   

2. 构建完成后会在 dist/ 目录下生成 .whl 文件，通过以下命令进行本地安装：

   pip install dist/py_wechat_ocr-0.1.0-py3-none-any.whl
   

开发者调试安装（编辑模式）

如果您想要对本项目进行二次开发或调试，可以使用编辑模式（Editable Mode）安装：

pip install -e .

快速上手

安装完成后，您可以直接在您的 Python 代码中导入并使用它：

from wechat_ocr import WeChatOCR

try:
    # 1. 初始化 OCR 引擎，需传入微信的实际安装路径
    # 引擎在首次运行时，会自动从该路径解压所需的 wxocr.dll 依赖文件
    wx_ocr = WeChatOCR(r"D:\Program Files\Tencent\Weixin")

    # 2. 识别指定图片
    print("开始识别...")
    result = wx_ocr.ocr_img("test.png")
    print("识别结果:", result)

    # 3. 如果需要保存识别后的 JSON 数据，可以将 save_json 设为 True
    # 识别结果将会自动保存在图片同目录下，命名为 test.png.json
    wx_ocr.ocr_img("test.png", save_json=True)

    # 4. 释放 OCR 引擎资源
    wx_ocr.close()
    print("微信 OCR 引擎已成功关闭。")

except Exception as e:
    print(f"运行期间发生错误: {e}")

核心 API 说明

WeChatOCR(wx_dir: str | Path)

• 作用：初始化 OCR 引擎环境。
• 参数：
  • wx_dir: 微信客户端的安装路径（例如 C:\Program Files\Tencent\Weixin）。引擎将在此目录的子文件夹中寻找版本目录，并自动释放、定位 wxocr.dll 核心库。

ocr_img(image_path: str, save_json: bool = False)

• 作用：对指定的图片进行 OCR 文字识别。
• 参数：
  • image_path: 需要识别的图片文件路径。
  • save_json: 是否在图片所在目录下输出一份同名 .json 结果文件，默认为 False。
• 返回值：返回识别出来的 JSON 字典，包含文字内容、坐标位置与置信度。

close()

• 作用：手动关闭底层的 OCR 引擎并释放内存。

常见问题解答

1. 为什么提示“未找到核心文件: WeChatOcr.bin”？ 请检查您传入的微信目录是否正确。本库需要在此目录下的子文件夹内找到类似 [版本号]\WeChatOcr.bin 的文件。如果微信安装在非常规路径下，请务必传入该非常规的微信安装根路径。
2. 能支持 Linux 或 macOS 吗？ 不支持。核心的解压、DLL 注入以及 wcocr.pyd 的编译代码深度绑定了 Windows 操作系统下的微信客户端依赖。

鸣谢

• 本项目所使用的二进制扩展模块 wcocr.pyd 编译自开源项目 swigger/wechat-ocr。非常感谢原作者的开源贡献！