Install & Compatibility
Where this runs
tested against v1.11.4 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.528s · 22.7MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 2.4s · import 0.499s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GoogleTranslator
✓ from deep_translator import GoogleTranslator
DeepLTranslator
✓ from deep_translator import DeepLTranslator
ChatGptTranslator
✓ from deep_translator import ChatGptTranslator
single_translation
✓ from deep_translator import single_translation
batch_translation
✓ from deep_translator import batch_translation
document_translation
✓ from deep_translator import document_translation
✗ from deep_translator.document import document_translation
As of v1.10.0, document_translation is directly importable from the top-level package.
This quickstart demonstrates translating text using `GoogleTranslator` and `DeepLTranslator`. `GoogleTranslator` typically works out-of-the-box, while `DeepLTranslator` requires an API key (preferably set as an environment variable) and the optional `deepl` dependency to be installed (`pip install "deep-translator[deepl]"`).
import os
from deep_translator import GoogleTranslator, DeepLTranslator
# Example 1: Google Translator (no API key typically required for basic use)
translated_text_google = GoogleTranslator(source='auto', target='fr').translate(text='Hello world!')
print(f"Google Translation: {translated_text_google}")
# Example 2: DeepL Translator (API key usually required for production/higher usage)
# Ensure deep-translator[deepl] is installed (pip install "deep-translator[deepl]")
deep_l_api_key = os.environ.get('DEEPL_API_KEY', '') # Load from environment variable
if deep_l_api_key:
try:
# use_free_api=True for DeepL Free API tier
translator = DeepLTranslator(api_key=deep_l_api_key, source='en', target='de', use_free_api=True)
translated_text_deepl = translator.translate(text='Hello world!')
print(f"DeepL Translation: {translated_text_deepl}")
except Exception as e:
print(f"DeepL translation failed: {e}. Check API key and installation.")
else:
print("DeepL API key not found (DEEPL_API_KEY). Skipping DeepL translation.")
Debug
Known issues
gotchaMany commercial or advanced translators (e.g., DeepL, ChatGPT, Baidu) require an API key from the respective service provider. Without a valid key, translation requests will fail or be severely rate-limited.fixObtain an API key from the service provider (e.g., DeepL, OpenAI). Pass it during translator initialization (`DeepLTranslator(api_key='YOUR_KEY', ...)`) or configure via environment variables (e.g., `OPENAI_API_KEY` for ChatGPT).
affects: All versions
breakingAs `deep-translator` relies on external, third-party translation APIs, changes in these APIs (e.g., endpoint alterations, rate limit policy changes) can cause specific translators to break without warning. This often necessitates updates to the `deep-translator` library.fixIf a translator unexpectedly stops working, check the `deep-translator` GitHub repository for reported issues or new releases addressing the problem. Update the library to the latest version to get fixes.
affects: All versions (impacts specific translators dynamically)
gotchaTo use certain translators (e.g., DeepL, ChatGPT, document translation), you must install `deep-translator` with specific optional dependencies using `pip install "deep-translator[translator_name]"` or `"deep-translator[all]"`. Forgetting this step will lead to `ImportError` or `ModuleNotFoundError`.fixInstall the necessary extras. For example, `pip install "deep-translator[deepl]"` for `DeepLTranslator`, `"deep-translator[chatgpt]"` for `ChatGptTranslator`, or `"deep-translator[document]"` for document processing.
affects: All versions
gotchaTranslators have underlying `max_chars` limits imposed by the external services. While `deep-translator` fixed an internal `max_chars` bug in v1.11.2, extremely long texts might still be rejected or truncated by the API, even if the local bug is resolved.fixFor very long texts, split the input into smaller, manageable chunks before translating. Consider using `batch_translation` if the chosen translator supports it efficiently.
affects: All versions (internal bug fixed in >=1.11.2, but external limits persist)
gotchaDocument translation (introduced in v1.10.0 for PDF and DOCX) has additional requirements. PDF translation relies on OCR via Tesseract, which needs to be installed as a system dependency and available in your PATH, alongside `pytesseract` and `PyPDF2` Python packages.fixInstall `pip install "deep-translator[document]"`. For PDFs, ensure Tesseract OCR is installed on your operating system and its executable is accessible in your system's PATH.
affects: >=1.10.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'deep_translator'
The Python interpreter cannot find the 'deep_translator' module. This often happens if the library is not installed, or if there's a mismatch between the installed package name (`deep-translator`) and the import statement (`deep_translator`), or if a bundling tool like PyInstaller fails to include it.
fixEnsure the library is correctly installed using `pip install deep-translator`. If using a bundling tool like PyInstaller, you might need to add `--hidden-import=deep_translator` to your build command. The correct import statement is `from deep_translator import ...`.
NotValidPayload: ... text must be a valid text with maximum 5000 character, otherwise it cannot be translated
The text provided for translation is either not a valid string, or its length exceeds the maximum character limit imposed by the underlying translation service (e.g., Google Translate often has a 5000-character limit per request).
fixVerify that the `text` argument is a string and its length does not exceed the translator's limit. For longer texts, implement logic to split the text into smaller chunks and translate them individually.
TranslationNotFound: No translation was found using the current translator. Try another translator?
The specific translator instance used (e.g., `GoogleTranslator`, `DeeplTranslator`) could not provide a translation for the given text. This can be due to various reasons, such as temporary network issues, rate limiting by the service, or the text content being unprocessable by that particular translator.
fixImplement error handling to catch `TranslationNotFound`. Consider retrying the translation after a short delay, trying a different translator available in `deep-translator`, or checking the input text for unusual formatting or content that might cause issues for the service.
InvalidSourceOrTargetLanguage: Invalid source or target language!
The language code provided for the `source` or `target` language parameter is not recognized or supported by the specific translation service being used within `deep-translator`.
fixConsult the `deep-translator` documentation or use the `get_supported_languages()` method on the specific translator class (e.g., `GoogleTranslator.get_supported_languages()`) to get a list of valid language codes. Ensure the codes match the required format (e.g., 'en' for English, 'fr' for French).
Upgrade
Version history
1.11.4latest on PyPI · released Jun 28, 2023
Audit
Dependencies
httpxrequiredCore dependency for making HTTP requests to various translation services.
beautifulsoup4requiredCore dependency for parsing HTML responses from some translators.
googletrans==4.0.0rc1requiredCore dependency for GoogleTranslator.
deeploptionalOptional dependency for DeepLTranslator, installed with the 'deepl' extra.
openaioptionalOptional dependency for ChatGptTranslator, installed with the 'chatgpt' extra.
requests_htmloptionalOptional dependency for MyMemory, Pons, Linguee, Yandex, Microsoft, Papago, and QCRI translators.
python-docxoptionalOptional dependency for translating .docx files, part of the 'document' extra.
PyPDF2optionalOptional dependency for reading .pdf files for translation, part of the 'document' extra.
pytesseractoptionalOptional dependency for OCR capabilities when translating PDFs/images, part of the 'document' extra.
baidu-aipoptionalOptional dependency for BaiduTranslator, installed with the 'baidu' extra.