Registry /
workflow / apache-airflow-providers-mongo
Install & Compatibility
Where this runs
tested against v5.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 5.740s · 262.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 24.6s · import 5.250s · 262MB
264MB installed
● package 264MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MongoHook
✓ from airflow.providers.mongo.hooks.mongo import MongoHook
MongoOperator
✓ from airflow.providers.mongo.operators.mongo import MongoOperator
MongoSensor
✓ from airflow.providers.mongo.sensors.mongo import MongoSensor
This quickstart demonstrates how to use the `MongoOperator` to insert a single document into a MongoDB collection. It assumes an Airflow connection named `mongodb_default` has been configured in the Airflow UI or via an environment variable. For MongoDB Atlas connections, ensure the 'Extra' field of the Airflow connection is correctly configured for SRV and SSL.
from __future__ import annotations
import os
from datetime import datetime
from airflow.models.dag import DAG
from airflow.providers.mongo.operators.mongo import MongoOperator
# Configure your MongoDB connection in Airflow UI or via environment variable.
# Example for environment variable:
# export AIRFLOW_CONN_MONGODB_DEFAULT='mongo://username:password@host:port/database?authSource=admin'
# For MongoDB Atlas (SRV record), use extra: {'srv': true, 'ssl': true}
# Example: export AIRFLOW_CONN_MONGODB_DEFAULT='mongo://username:password@cluster.mongodb.net/?retryWrites=true&w=majority'
# Then, in Airflow UI, edit the connection and add {"srv": true, "ssl": true} to the 'Extra' field.
# The 'Host' should be your cluster name, e.g., 'cluster0.abcde.mongodb.net'
with DAG(
dag_id='mongo_insert_example',
start_date=datetime(2023, 1, 1),
schedule=None,
catchup=False,
tags=['mongodb', 'example'],
doc_md="""### MongoDB Insert Example DAG
This DAG demonstrates how to use the MongoOperator to insert a document into a MongoDB collection.
Ensure you have an Airflow connection named 'mongodb_default' configured for your MongoDB instance.
"""
) as dag:
insert_document_task = MongoOperator(
task_id='insert_sample_document',
mongo_conn_id='mongodb_default', # This refers to the Airflow connection ID
database='mydatabase',
collection='mycollection',
operation='insert_one',
document={'name': 'Alice', 'age': 30, 'city': 'New York'}
)
airflow --version
Debug
Known issues
breakingThe `conn_id` parameter in `MongoHook` was removed and replaced by `mongo_conn_id`. Direct usage of `conn_id` will result in errors.fixUpdate all instances of `MongoHook(conn_id=...)` to `MongoHook(mongo_conn_id=...)`.
affects: >=5.3.4
breakingThe minimum supported Apache Airflow version for `apache-airflow-providers-mongo` has consistently increased with provider updates. Version 5.3.4 requires Airflow >=2.11.0. Older provider versions require earlier Airflow versions, e.g., 5.1.0 requires 2.10+, 4.2.0 requires 2.8+, and 4.0.0 requires 2.7+.fixEnsure your Airflow environment meets the minimum version requirement for the installed provider package. Upgrade Airflow if necessary.
affects: All versions, specifically 5.3.4 requires >=2.11.0
gotchaSince provider version 4.0.0, the `allow_insecure` flag in the MongoDB connection's 'Extra' field defaults to `False` when SSL encryption (`ssl=True`) is enabled. This means insecure SSL connections are not permitted by default.fixIf you explicitly require insecure SSL connections, you must set `allow_insecure: true` in the 'Extra' JSON field of your Airflow MongoDB connection. For secure connections, no action is needed as `allow_insecure` defaults to `False`.
affects: >=4.0.0
gotchaThere was an issue where setting `ssl=False` in the connection 'Extra' field, especially when combined with `srv=True` for DNS seedlists, did not correctly disable SSL/TLS, potentially leading to connection errors. This was noted as fixed in a patch for 4.x versions (related to #37214).fixEnsure you are on provider version 4.x or newer if you encounter issues with `ssl=False` and `srv=True` combination. Verify your MongoDB connection string and 'Extra' settings are correctly formed according to PyMongo's and Airflow's documentation.
affects: <4.x (prior to fix for #37214)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'airflow.providers.mongo.hooks.mongo'
The 'apache-airflow-providers-mongo' package is not installed or not properly configured.
fixEnsure the package is installed by running 'pip install apache-airflow-providers-mongo'.
ModuleNotFoundError: No module named 'pymongo'
The 'pymongo' library, required by 'apache-airflow-providers-mongo', is not installed.
fixInstall 'pymongo' by running 'pip install pymongo'.
ImportError: cannot import name 'MongoHook' from 'airflow.providers.mongo.hooks.mongo'
The 'MongoHook' class has been moved or renamed in the 'apache-airflow-providers-mongo' package.
fixUpdate the import statement to 'from airflow.providers.mongo.hooks.mongo import MongoHook'.
AttributeError: 'bool' object has no attribute 'lower'
This error typically occurs when a boolean value (e.g., `true` or `false`) is provided directly in the 'Extra' field of the Airflow MongoDB connection UI, but the hook expects it as a string.
fixIn the Airflow UI for the MongoDB connection, ensure that boolean values in the 'Extra' field are represented as strings (e.g., `"true"` instead of `true` or `"false"` instead of `false`). For example, `{"allow_insecure": "true"}`. MongoServerError: Authentication failed
This error indicates that the MongoDB server rejected the provided credentials, often due to an incorrect username, password, authentication database (`authSource`), or improper URL encoding of special characters in the connection string.
fixVerify the username and password in your Airflow MongoDB connection details, ensure special characters in credentials are URL-encoded, confirm the correct `authSource` is specified in the 'Schema' or 'Extra' field (e.g., `?authSource=admin`), and check that the MongoDB user has the necessary permissions.
Upgrade
Version history
5.4.0latest on PyPI · released May 23, 2026
Audit
Dependencies
apache-airflowrequiredThis is an Airflow provider package and requires a compatible Airflow installation. Version 5.3.4 requires Airflow >=2.11.0.
pymongorequiredThe underlying Python driver for MongoDB interaction used by MongoHook.
dnspythonoptionalRequired for using DNS seedlist (SRV records) in MongoDB connection strings.