PyMongo：Python 连接 MongoDB 的官方驱动

MongoDB 官方维护的 Python 数据库驱动 PyMongo，在 GitHub 上获得了 4,344 个 Star：

PyMongo 是 MongoDB 官方推出的 Python 数据库驱动，也是 Python 生态中连接 MongoDB 的首选方案。同步和异步 API 双轨并行，月下载量长期保持在千万级别。

PyMongo 发行版包含三个核心模块：pymongo 是原生的 Python MongoDB 驱动；bson 实现了 BSON 二进制序列化格式的完整编解码支持；gridfs 则是在 PyMongo 之上实现的 GridFS 文件存储规范，用于处理超过 16MB 的大文件存取。

版本支持覆盖从 MongoDB 4.0 到 8.0 共六个大版本，同时兼容 CPython 3.9 以上和 PyPy3.9 以上。项目遵循语义化版本规范进行发布，API 稳定性有明确的保障。

---

安装

安装方式很直接，一行 pip 命令即可：

python -m pip install pymongo

也可以克隆仓库从源码安装：

pip install .

需要特别注意的是，不要安装 PyPI 上名为 bson 的第三方包。PyMongo 自带 bson 模块，两个包会互相冲突。

---

可选依赖

PyMongo 通过 extras 机制管理可选依赖，按需安装即可。

mongodb+srv:// 协议的 URI 解析需要 dnspython。

GSSAPI 认证在 Unix 上依赖 pykerberos，Windows 上依赖 WinKerberos：

python -m pip install "pymongo[gssapi]"

MONGODB-AWS 认证需要 pymongo-auth-aws：

python -m pip install "pymongo[aws]"

OCSP 在线证书状态协议需要 PyOpenSSL 和 requests：

python -m pip install "pymongo[ocsp]"

传输层压缩方面，snappy 需要 python-snappy，zstandard 需要 backports.zstd（Python 3.14 之前版本）：

python -m pip install "pymongo[snappy]"
python -m pip install "pymongo[zstd]"

客户端字段级加密需要 pymongocrypt 和 pymongo-auth-aws：

python -m pip install "pymongo[encryption]"

一次性装齐所有可选依赖：

python -m pip install "pymongo[gssapi,aws,ocsp,snappy,zstd,encryption]"

---

基本用法

PyMongo 的 API 设计贴近 MongoDB Shell 的使用习惯。连接数据库、选择集合、执行 CRUD 操作都很直观：

>>> import pymongo
>>> client = pymongo.MongoClient("localhost", 27017)
>>> db = client.test
>>> db.my_collection.insert_one({"x": 10}).inserted_id
ObjectId('4aba15ebe23f6b53b0000000')
>>> db.my_collection.find_one()
{'x': 10, '_id': ObjectId('4aba15ebe23f6b53b0000000')}
>>> for item in db.my_collection.find():
...     print(item["x"])
...
10
8
11
>>> db.my_collection.create_index("x")
'x_1'
>>> [item["x"] for item in db.my_collection.find().limit(2).skip(1)]
[8, 11]

创建索引、排序、分页等操作都内建支持，不需要额外封装。

同步 API 之外，PyMongo 还提供了异步 API，可以在 asyncio 环境下配合网络框架使用，满足高并发场景下的数据库访问需求。

---

测试与贡献

项目配备了完善的测试套件。安装测试依赖后在仓库根目录执行 pytest 即可：

pip install -e ".[test]"
pytest

遇到问题可以在 StackOverflow 上使用 mongodb 标签提问，社区活跃度很高。Bug 报告和功能请求通过 JIRA 的 PYTHON 项目提交，所有驱动的 Bug 报告均为公开可见。安全问题则按照 MongoDB 官方渠道单独上报。

MongoDB Learn 平台上有专门的 Python 课程，开发者中心也持续更新 Python 技术文章，覆盖从基础连接到性能优化的各类场景。

所有驱动的 Bug 报告均为公开可见。安全问题则按照 MongoDB 官方渠道单独上报。

MongoDB Learn 平台上有专门的 Python 课程，开发者中心也持续更新 Python 技术文章，覆盖从基础连接到性能优化的各类场景。