Install & Compatibility
Where this runs
tested against v2.4.49 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.955s · 97MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.3s · import 0.966s · 97MB
105MB installed
● package 105MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mavutil
✓ from pymavlink import mavutil
mavlink
✓ from pymavlink import mavlink
✗ import mavlink
While `import mavlink` might sometimes work if generated files are in PYTHONPATH, the recommended way is `from pymavlink import mavlink` or accessing it via a `mavutil.mavlink_connection` instance, which ensures the correct dialect is loaded.
dialects
✓ from pymavlink.dialects import ardupilotmega as m
✗ from pymavlink.mavlink import MAVLink_HEARTBEAT_MESSAGE
MAVLink message definitions are generated into specific dialects (e.g., `ardupilotmega`, `common`, `minimal`). It's crucial to import messages from the correct dialect, or rely on `mavutil.mavlink_connection` to handle dialect loading implicitly.
This quickstart demonstrates how to establish a MAVLink connection, request a data stream, and receive and process messages from a MAVLink-enabled device (e.g., a drone autopilot or a SITL simulator). It connects to a configurable MAVLink endpoint, requests all data streams, and then listens for and prints HEARTBEAT and ATTITUDE messages for 10 seconds. Ensure a MAVLink source is available at the specified connection string for the script to function.
import os
import time
from pymavlink import mavutil
# Define the connection string for your MAVLink device
# Examples: 'udp:127.0.0.1:14550' (for SITL), 'serial:/dev/ttyACM0:115200' (for a USB serial device)
# You can set the MAVLINK_CONNECTION_STRING environment variable or change this directly.
connection_string = os.environ.get('MAVLINK_CONNECTION_STRING', 'udp:127.0.0.1:14550')
print(f"Attempting to connect to MAVLink device via: {connection_string}...")
try:
# Establish a MAVLink connection. wait_ready=True blocks until the first HEARTBEAT is received.
master = mavutil.mavlink_connection(connection_string, baud=115200, wait_ready=True)
print(f"Connection established! System ID: {master.target_system}, Component ID: {master.target_component}")
# Request an ATTITUDE data stream at 1Hz
# MAV_DATA_STREAM_ALL for all streams, or specific ones like MAV_DATA_STREAM_EXTRA1 for ATTITUDE
# The last '1' is the rate in Hz, '0' would stop the stream.
master.mav.request_data_stream_send(
master.target_system, master.target_component,
mavutil.mavlink.MAV_DATA_STREAM_ALL, 1, 1
)
print("Requested data stream for all messages at 1Hz.")
print("Listening for HEARTBEAT and ATTITUDE messages for 10 seconds...")
start_time = time.time()
while (time.time() - start_time) < 10: # Listen for 10 seconds
# Non-blocking receive for specific message types
msg = master.recv_match(type=['HEARTBEAT', 'ATTITUDE'], blocking=False, timeout=0.1)
if msg:
print(f"Received {msg.get_type()} - {msg}")
if msg.get_type() == 'ATTITUDE':
print(f" Roll: {msg.roll:.2f} deg, Pitch: {msg.pitch:.2f} deg, Yaw: {msg.yaw:.2f} deg")
time.sleep(0.01) # Small delay to prevent busy-waiting
print("Finished listening for messages.")
except Exception as e:
print(f"Error during MAVLink communication: {e}")
mavlink --version
Debug
Known issues
breakingMAVLink protocol version 1 (MAVLink1) and version 2 (MAVLink2) are incompatible. MAVLink2 introduces message signing, longer message names, and expanded component IDs. pymavlink defaults to MAVLink2, but if connecting to an older MAVLink1 device, you must explicitly specify the protocol version.fixWhen creating a connection, explicitly set the dialect: `master = mavutil.mavlink_connection(connection_string, dialect='mavlink10')`. Ensure your target device is configured to use the correct protocol version.
affects: All versions (protocol specific)
gotchaMAVLink message definitions are dialect-specific (e.g., 'ardupilotmega', 'common', 'minimal'). Messages or fields available in one dialect might not exist or have different structures in another. Using the wrong dialect can lead to `AttributeError` when accessing fields or `KeyError` if messages are missing.fixIdentify the correct MAVLink dialect used by your target device. When creating a `mavutil.mavlink_connection`, the dialect is often auto-detected or can be explicitly set (e.g., `dialect='ardupilotmega'`). If manually constructing messages, import from the specific dialect: `from pymavlink.dialects.ardupilotmega import MAVLink_ATTITUDE_MESSAGE`.
affects: All versions
deprecatedPython 2 support has been officially dropped. While older pymavlink versions might still have some Python 2 compatibility, active development, new features, and bug fixes are exclusively for Python 3. Attempting to use recent versions with Python 2 may result in unexpected errors or missing functionality.fixMigrate your environment to Python 3.6+ to ensure full compatibility, receive the latest updates, and benefit from ongoing support. The `future` dependency remains primarily for transitional compatibility.
affects: >=2.4.40
gotchaUsing `master.recv_match(blocking=True)` can halt your application indefinitely if no message matches the criteria, especially in single-threaded contexts. This can lead to unresponsive interfaces or deadlocks.fixFor responsive applications, use `blocking=False` in conjunction with a `timeout` within a loop. This allows your program to perform other tasks or handle periods of no incoming data. Example: `msg = master.recv_match(type=['HEARTBEAT'], blocking=False, timeout=0.1)`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pymavlink'
This error typically occurs because the `pymavlink` package is not installed in the Python environment being used, or the Python interpreter cannot find the installed package due to an incorrect PYTHONPATH or virtual environment activation.
fixEnsure `pymavlink` is installed for your active Python interpreter: `pip install pymavlink` or `python -m pip install pymavlink`. If using a virtual environment, ensure it is activated before installation and running your script.
ERROR: Failed building wheel for pymavlink
...
AttributeError: 'array.array' object has no attribute 'fromstring'
This error often arises during the installation of `pymavlink` (especially older versions) on newer Python environments, particularly Python 3.10+, due to an incompatibility in the `mavcrc.py` generation script with how Python handles string conversion from byte arrays.
fixTry updating `setuptools` and `pip` before installing: `pip install --upgrade setuptools pip`. If the issue persists, installing a specific, potentially newer, version of `pymavlink` might resolve it, or ensure your Python version is compatible with the `pymavlink` version you are trying to install.
AttributeError: 'module' object has no attribute '_doc_'
This error occurs when attempting to access the `__doc__` (dunder doc) attribute of the `pymavlink` module using a single underscore (`_doc_`) instead of the correct double underscores (`__doc__`).
fixCorrect the attribute access to use double underscores: `print(pymavlink.__doc__)`.
AttributeError: module 'pymavlink.dialects.v20.common' has no attribute 'MAV_CMD_SET_CAMERA_ZOOM'
This error indicates that a specific MAVLink command or message field, like `MAV_CMD_SET_CAMERA_ZOOM`, is not recognized or defined in the currently loaded `pymavlink` dialect (e.g., `v20.common`). This can happen if the `pymavlink` version is outdated, or if the MAVLink message definition (XML) used to generate the Python dialect does not include that specific command. It can also occur if the code expects MAVLink v2.0 but `pymavlink` defaults to v1.0.
fixEnsure `pymavlink` is updated to the latest version: `pip install --upgrade pymavlink`. If the command is new or custom, verify your MAVLink XML definitions are up-to-date and that `pymavlink` was generated or installed with those definitions. For MAVLink v2.0 specific commands, ensure `MAVLINK20=1` is set as an environment variable or passed to `mavutil.mavlink_connection`.
SerialException: 'Serial' object has no attribute 'setBaudrate'
This error occurs because older versions of `pymavlink` (or its dependency, `MAVProxy`) use the `setBaudrate()` method which was removed or changed in `pySerial` version 3.0 and later.
fixDowngrade `pySerial` to a compatible version, typically `pySerial` version 2.x, by running: `pip install "pyserial>=2.0,<3.0"`. Alternatively, update `pymavlink` to a version that is compatible with `pySerial` 3.x if available.
Upgrade
Version history
2.4.49latest on PyPI · released Aug 1, 2025
Audit
Dependencies
futurerequiredProvides Python 2/3 compatibility helpers, though modern pymavlink targets Python 3.
lxmlrequiredRequired for parsing MAVLink XML definition files to generate message classes.
pyserialoptionalCommonly required for serial port communication with MAVLink devices.