{"id":5176,"library":"deepl","title":"DeepL Python Library","description":"The DeepL Python Library is an official client for the DeepL API, providing a convenient way for Python applications to interact with DeepL's language AI for high-quality text and document translation. It supports all major API functions and is actively maintained with frequent releases, currently at version 1.30.0.","status":"active","version":"1.30.0","language":"en","source_language":"en","source_url":"https://github.com/DeepLcom/deepl-python","tags":["translation","api client","natural language processing","ai"],"install":[{"cmd":"pip install --upgrade deepl","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version. Officially tested with 3.9 to 3.13.","package":"python","optional":false,"max_version":"4","min_version":"3.9"},{"reason":"Used for HTTP requests.","package":"requests","optional":false,"min_version":"2.32.4"}],"imports":[{"note":"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.","wrong":"import deepl\ntranslator = deepl.Translator(auth_key)","symbol":"DeepLClient","correct":"import deepl\ndeepL_client = deepl.DeepLClient(auth_key)"}],"quickstart":{"code":"import os\nimport deepl\n\nauth_key = os.environ.get(\"DEEPL_AUTH_KEY\", \"\") # Replace with your key or set DEEPL_AUTH_KEY environment variable\nif not auth_key:\n    print(\"Please set the DEEPL_AUTH_KEY environment variable.\")\n    exit(1)\n\n# For DeepL API Free, use server_url=\"https://api-free.deepl.com\"\ndeepL_client = deepl.DeepLClient(auth_key)\n\ntext_to_translate = \"Hello, world!\"\ntarget_language = \"FR\"\n\ntry:\n    result = deepL_client.translate_text(text_to_translate, target_lang=target_language)\n    print(f\"Translated text: {result.text}\")\n    print(f\"Detected source language: {result.detected_source_lang}\")\nexcept deepl.exceptions.DeepLException as e:\n    print(f\"Error during translation: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or higher.","message":"Dropped support for Python 3.8 and older versions.","severity":"breaking","affected_versions":">=1.23.0"},{"fix":"Ensure 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.","message":"DeepL 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.","severity":"breaking","affected_versions":"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."},{"fix":"Avoid explicitly setting `model_type='latency_optimized'` when also providing `custom_instructions`. Allow the default `quality_optimized` or choose a compatible model type.","message":"When 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.","severity":"gotcha","affected_versions":">=1.26.0"},{"fix":"Initialize 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`).","message":"The DeepL API uses different endpoints for Free and Pro accounts. Free users must specify `server_url=\"https://api-free.deepl.com\"` when initializing `DeepLClient`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use 'EN-US' for American English or 'EN-GB' for British English as `target_lang`.","message":"The generic 'EN' language code for target languages is deprecated. You must use a specific regional variant.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Handle `deepl.exceptions.QuotaExceededException` to inform the user or prompt for account changes. Monitor your DeepL account usage and cost control settings.","message":"The 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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"For `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.","message":"In `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.","severity":"gotcha","affected_versions":"<1.28.0"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}