Install & Compatibility
Where this runs
tested against v1.15.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
py 3.9
✕ build_error
✕ build_error
415MB installed
● package 415MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RTCPeerConnection
✓ from aiortc import RTCPeerConnection
RTCSessionDescription
✓ from aiortc import RTCSessionDescription
RTCConfiguration
✓ from aiortc import RTCConfiguration
MediaStreamTrack
✓ from aiortc.mediastreams import MediaStreamTrack
VideoStreamTrack
✓ from aiortc.mediastreams import VideoStreamTrack
AudioStreamTrack
✓ from aiortc.mediastreams import AudioStreamTrack
RTCDataChannel
✓ from aiortc import RTCDataChannel
RTCCertificate
✓ from aiortc import RTCCertificate
generateCertificate
✓ from aiortc import RTCCertificate, generateCertificate
A class method of RTCCertificate, often imported alongside it.
MediaRelay
✓ from aiortc.contrib.media import MediaRelay
✗ from aiortc import MediaRelay
MediaRelay is in the 'contrib.media' submodule, not directly under 'aiortc'.
MediaPlayer
✓ from aiortc.contrib.media import MediaPlayer
✗ from aiortc import MediaPlayer
MediaPlayer is in the 'contrib.media' submodule, not directly under 'aiortc'.
This quickstart demonstrates the basic setup of an `RTCPeerConnection` and the generation of an SDP offer. In a full WebRTC application, this offer would be exchanged with a remote peer via a signaling server, and an answer would be received and set as the remote description. The example includes placeholders for a simulated answer and a loop to keep the connection alive. It highlights the core `RTCPeerConnection` object and its `createOffer` and `setLocalDescription` methods. For practical examples with media and data channels, refer to the `aiortc` examples directory on GitHub, especially the `server` example.
import asyncio
from aiortc import RTCPeerConnection, RTCSessionDescription
async def main():
pc = RTCPeerConnection()
print("RTCPeerConnection created.")
# Example: Create an offer (typically this is exchanged via a signaling server)
offer = await pc.createOffer()
await pc.setLocalDescription(offer)
print(f"Local SDP Offer:\n{pc.localDescription.sdp}")
# In a real application, you'd send pc.localDescription to a remote peer
# and receive their answer, then set it as remoteDescription.
# For this quickstart, we'll simulate a minimal answer (not fully functional for media).
# Simulate receiving an answer (replace with actual signaling in a real app)
# For a real peer, this would be generated by the remote peer's createAnswer()
# and contain media tracks if applicable.
# remote_sdp_answer = "v=0\r\no=- 12345 12345 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=fingerprint:sha-256 A0:B1:C2:D3:E4:F5:G6:H7:I8:J9:K0:L1:M2:N3:O4:P5:Q6:R7:S8:T9:U0:V1:W2:X3:Y4\r\na=group:BUNDLE audio video\r\na=msid-semantic:WMS\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111\r\na=rtcp-mux\r\na=rtpmap:111 OPUS/48000/2\r\na=mid:audio\r\nm=video 9 UDP/TLS/RTP/SAVPF 96\r\na=rtcp-mux\r\na=rtpmap:96 VP8/90000\r\na=mid:video\r\n"
# remote_description = RTCSessionDescription(sdp=remote_sdp_answer, type="answer")
# await pc.setRemoteDescription(remote_description)
# print("Remote SDP Answer set (simulated).")
# Keep the connection alive for a short period or until closed by events
try:
while pc.connectionState != "closed" and pc.connectionState != "failed":
await asyncio.sleep(1)
except asyncio.CancelledError:
pass
finally:
print("Closing peer connection...")
await pc.close()
print("Peer connection closed.")
if __name__ == "__main__":
# Ensure auth check passes for quickstart (not applicable for aiortc directly)
# For real use cases, replace os.environ.get with actual credentials if needed by signaling.
# Example: if you had a signaling server requiring a token:
# import os
# if not os.environ.get('WEBRTC_AUTH_TOKEN'):
# print("Warning: WEBRTC_AUTH_TOKEN not set. Quickstart might fail in a real scenario.")
asyncio.run(main())
Debug
Known issues
breakingThe `RTCDataChannel.send` method has historically changed between being a regular function and a coroutine. While currently a coroutine, be aware of this breaking change if upgrading from older versions, particularly around 0.9.x.fixEnsure `await` is used when calling `RTCDataChannel.send()` if you are on a version where it's a coroutine. Review the changelog for specific version behavior.
affects: < 1.0.0 (specifically 0.9.0, 0.9.1, and subsequent changes before 1.0.0)
breakingOlder Python versions are no longer supported. aiortc dropped support for Python 3.5 (0.9.23), 3.6 (1.3.0), and 3.8 (1.10.0).fixEnsure your environment uses Python 3.10 or newer to be compatible with the latest aiortc releases.
affects: >= 0.9.23 for Python 3.5, >= 1.3.0 for Python 3.6, >= 1.10.0 for Python 3.8
gotchaWhen using `MediaRecorder` with `PyAV` for video, the default resolution can be hardcoded to 640x480, and `aiortc` might not automatically adjust it. This can lead to unexpected video sizes if not explicitly handled.fixExplicitly configure the video size when initializing `MediaPlayer` or `MediaRecorder` if a different resolution is desired.
affects: All versions (behavior tied to underlying PyAV defaults)
gotchaFor outgoing media tracks, it is crucial to establish and add the track to the `RTCPeerConnection` *before* the server sends back the ICE response during the signaling process. Failing to do so can result in the peer connection opening in a 'recvonly' mode, preventing the sending of media.fixEnsure your signaling logic properly synchronizes the addition of outgoing tracks with the exchange of ICE candidates and SDP answers.
affects: All versions
gotchaThe `MediaRecorder` consumes incoming tracks and does not natively manage presentation timestamp (PTS) gaps caused by network interruptions. Directly recording an incoming track with `MediaRecorder` can lead to reception halting if there are PTS discontinuities.fixFor scenarios requiring robust recording of incoming tracks while also re-transmitting them, use a `MediaRelay` to duplicate the track and feed one stream to the `MediaRecorder` and the other to the outgoing peer connection. Implement custom logic to handle PTS adjustments if direct recording of lossy streams is necessary.
affects: All versions
Errors
Common errors & fixes
fatal error C1083: The included file cannot be opened: 'libavutil/mathematics.h': No such file or directory
This error occurs when the required FFmpeg development libraries are missing during the installation of aiortc.
fixInstall the FFmpeg development libraries appropriate for your operating system before installing aiortc.
Uncaught TypeError: Cannot read property 'getUserMedia' of undefined
This error occurs when attempting to access `getUserMedia` on an insecure origin, as browsers restrict this API to secure contexts.
fixServe your application over HTTPS or configure your browser to treat the origin as secure for development purposes.
ValueError: None is not in list
This error occurs when there is a mismatch in the SDP negotiation, often due to missing or incorrect media tracks.
fixEnsure that both peers have matching media tracks and that the SDP negotiation process is correctly implemented.
IndexError: list index out of range
This error occurs when parsing an SDP answer that lacks expected SSRC attributes, leading to an attempt to access a non-existent list element.
fixVerify that the SDP answer includes the necessary SSRC attributes and that the remote description is correctly set.
ConnectionError: Cannot send encrypted data, not connected
This error occurs when attempting to send data over an SCTP transport that is not fully established.
fixEnsure that the SCTP transport is connected before sending data, and handle connection state changes appropriately.
Upgrade
Version history
1.15.0latest on PyPI · released Jul 13, 2026
Audit
Dependencies
cryptographyrequiredSecurity-related cryptographic operations.
pylibsrtprequiredSecure Real-time Transport Protocol (SRTP) implementation.
avrequiredPythonic bindings for FFmpeg, used for media processing.
google-crc32crequiredFast CRC-32C computation.
pyopensslrequiredSSL/TLS toolkit.
aioicerequiredInteractive Connectivity Establishment (ICE) implementation.
pyeerequiredEvent emitter library, similar to Node.js EventEmitter.
aiohttpoptionalOften used for signaling server implementations in examples.
opencv-pythonoptionalUsed in examples for video frame processing (e.g., computer vision).