Install & Compatibility
Where this runs
tested against v7.7.1 · 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 0.730s · 42.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.7s · import 0.696s · 42MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DeepgramClient
✓ from deepgram import DeepgramClient
✗ from deepgram import Deepgram
The `Deepgram` client was used in v5 and earlier; `DeepgramClient` is the current client in v6.
EventType
✓ from deepgram.core.events import EventType
Used for handling WebSocket events.
ListenV2Options
✓ from deepgram.listen.v2.options import ListenV2Options
Types are now imported from their feature-specific namespaces in v6.
This quickstart demonstrates how to initialize the DeepgramClient, configure it with an API key from environment variables, and establish a real-time WebSocket connection to the Deepgram Listen API (v2) for transcribing audio. It includes basic event handlers for connection status and incoming transcripts.
import os
from deepgram import DeepgramClient, DeepgramClientOptions, LiveTranscriptionEvents
# Ensure you have your Deepgram API key set as an environment variable (DEEPGRAM_API_KEY or DEEPGRAM_TOKEN)
API_KEY = os.environ.get('DEEPGRAM_API_KEY') or os.environ.get('DEEPGRAM_TOKEN')
if not API_KEY:
raise ValueError("DEEPGRAM_API_KEY or DEEPGRAM_TOKEN environment variable not set.")
# Configure the client options for best performance and compatibility
config = DeepgramClientOptions(verbose=1)
deepgram = DeepgramClient(API_KEY, config=config)
# For real-time streaming, connect to the Listen API
# This example demonstrates a synchronous connection for simplicity,
# but async methods are also available.
def main():
try:
# Connect to the real-time Listen API (v2)
connection = deepgram.listen.v2.live.connect()
# Define event handlers
def on_message(self, result, **kwargs):
if result.speech_final: # Only print final transcripts
print(f"Speaker: {result.speaker}") # Assuming speaker diarization is enabled
print(f"Transcript: {result.channel.alternatives[0].transcript}")
def on_open(self, open, **kwargs):
print("Connection opened.")
def on_close(self, close, **kwargs):
print("Connection closed.")
def on_error(self, error, **kwargs):
print(f"Error: {error}")
# Register event handlers
connection.on(LiveTranscriptionEvents.Open, on_open)
connection.on(LiveTranscriptionEvents.Transcript, on_message)
connection.on(LiveTranscriptionEvents.Close, on_close)
connection.on(LiveTranscriptionEvents.Error, on_error)
# Start sending audio data (in a real app, this would be from a microphone or audio file)
# For this example, we'll just send a dummy message and close.
print("Sending dummy data... (in a real app, send actual audio bytes)")
# In a real application, you would continuously send bytes from an audio source:
# connection.send_data(audio_chunk_bytes)
# For now, simulate sending options
connection.send_options({
"model": "nova-2",
"language": "en-US",
"punctuate": True,
"diarize": True,
"smart_format": True
})
import time
time.sleep(5) # Keep connection open for a bit to simulate processing
# Don't forget to close the connection when done
connection.finish()
except Exception as e:
print(f"Could not open connection: {e}")
if __name__ == "__main__":
main()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'deepgram'
The `deepgram-sdk` package is not installed or the Python environment where the code is run does not have it installed.
fixEnsure the deepgram-sdk is installed in your active Python environment: `pip install deepgram-sdk`
DeepgramSetupError: Invalid API key
The Deepgram SDK was initialized with an API key that is invalid, expired, or has incorrect formatting (e.g., leading/trailing whitespace).
fixVerify your Deepgram API key in the Deepgram Console, ensuring it is correct, active, and copied without extra characters. Pass the correct key to `DeepgramClient(api_key="YOUR_API_KEY")` or set the `DEEPGRAM_API_KEY` environment variable.
TypeError: got an unexpected keyword argument 'extra_headers'
This error typically occurs due to an incompatibility between the `deepgram-sdk` and a newer version of the `websockets` library, where the `extra_headers` parameter was renamed or changed.
fixDowngrade the `websockets` library to a compatible version, often `websockets<14` (e.g., `pip install 'websockets<14'`)
401 Unauthorized
The request to the Deepgram API was made without a valid API key, or the provided API key is incorrect or lacks the necessary permissions.
fixProvide a valid Deepgram API key via the `Authorization` header, the `api_key` parameter in the SDK client, or the `DEEPGRAM_API_KEY` environment variable. Ensure the key has the required permissions for the endpoint you are accessing.
422 Unprocessable Entity
Deepgram was unable to process the request, commonly because the audio data sent was incomplete, corrupted, or in an unsupported format, or the connection was closed prematurely.
fixVerify that the audio data is valid, complete, and in a format supported by Deepgram. Ensure the streaming connection remains open until all audio is sent, and check client-side logs for interrupted uploads or timeouts.
Upgrade
Version history
7.7.1latest on PyPI · released Aug 25, 2026
Audit
Dependencies
deepgram-sagemakeroptionalRequired for using Deepgram models on AWS SageMaker endpoints.