Install & Compatibility
Where this runs
tested against v1.32.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 0.410s · 21.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.382s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DeepLClient
✓ import deepl
deepL_client = deepl.DeepLClient(auth_key)
✗ import deepl
translator = deepl.Translator(auth_key)
The `Translator` class was used in earlier versions (e.g., prior to v1.0.0 and in some older documentation) but `DeepLClient` is the current and recommended class for interacting with the API.
Initializes the DeepLClient with an API key, preferably from an environment variable, and performs a basic text translation. Note the `server_url` option for DeepL API Free users.
import os
import deepl
auth_key = os.environ.get("DEEPL_AUTH_KEY", "") # Replace with your key or set DEEPL_AUTH_KEY environment variable
if not auth_key:
print("Please set the DEEPL_AUTH_KEY environment variable.")
exit(1)
# For DeepL API Free, use server_url="https://api-free.deepl.com"
deepL_client = deepl.DeepLClient(auth_key)
text_to_translate = "Hello, world!"
target_language = "FR"
try:
result = deepL_client.translate_text(text_to_translate, target_lang=target_language)
print(f"Translated text: {result.text}")
print(f"Detected source language: {result.detected_source_lang}")
except deepl.exceptions.DeepLException as e:
print(f"Error during translation: {e}")
Debug
Known issues
breakingDropped support for Python 3.8 and older versions.fixUpgrade your Python environment to version 3.9 or higher.
affects: >=1.23.0
breakingDeepL API deprecation of GET requests to /translate endpoint and query parameter authentication for all endpoints. While the `deepl-python` library versions 1.0.0+ handle this internally, direct API users or those using older versions of the client library (prior to v1.0.0) might be affected.fixEnsure you are using `deepl-python` library version 1.0.0 or newer. All authentication should be done via the `Authorization` HTTP header, which the library handles automatically when initialized with an `auth_key`. Direct API calls to `/translate` should use POST requests with data in the request body.
affects: DeepL API changes effective March 14, 2025 (for GET/query param auth) and November 2025 (for query parameter/request body auth). Library versions >=1.0.0 are unaffected.
gotchaWhen using the `custom_instructions` parameter in `translate_text()`, the API will default to the `quality_optimized` model type. Combining `custom_instructions` with the `latency_optimized` model type will result in an error.fixAvoid explicitly setting `model_type='latency_optimized'` when also providing `custom_instructions`. Allow the default `quality_optimized` or choose a compatible model type.
affects: >=1.26.0
gotchaThe DeepL API uses different endpoints for Free and Pro accounts. Free users must specify `server_url="https://api-free.deepl.com"` when initializing `DeepLClient`.fixInitialize the client with the correct `server_url` parameter: `deepl.DeepLClient(auth_key, server_url="https://api-free.deepl.com")` for free accounts, or omit for Pro accounts (default is `https://api.deepl.com`).
affects: All versions
gotchaThe generic 'EN' language code for target languages is deprecated. You must use a specific regional variant.fixUse 'EN-US' for American English or 'EN-GB' for British English as `target_lang`.
affects: All versions
gotchaThe library implements retries with exponential backoff for HTTP 429 (too many requests) and 500 (internal server error) responses. However, HTTP 456 (quota exceeded) indicates your account's character limit has been reached and requires user action (upgrading plan or increasing cost control limits).fixHandle `deepl.exceptions.QuotaExceededException` to inform the user or prompt for account changes. Monitor your DeepL account usage and cost control settings.
affects: All versions
gotchaIn `v1.28.0`, the `NotFoundException` error message was improved by removing the misleading 'check server_url' suggestion. This implies that previously, users might have incorrectly tried to change `server_url` for 404 errors that were not related to endpoint configuration.fixFor `NotFoundException` (HTTP 404), ensure the resource (e.g., glossary ID, style rule ID) exists and the API key is correct, rather than assuming a `server_url` misconfiguration. Upgrade to `v1.28.0` or newer for clearer error messages.
affects: <1.28.0
Upgrade
Version history
1.32.0latest on PyPI · released Aug 13, 2026
Audit
Dependencies
pythonrequiredRequired Python version. Officially tested with 3.9 to 3.13.
requestsrequiredUsed for HTTP requests.