Install & Compatibility
Where this runs
tested against v2.1.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.920 runs
installs and imports cleanly · install 0.0s · import 0.084s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.078s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LibreTranslateAPI
✓ from libretranslatepy import LibreTranslateAPI
This quickstart demonstrates how to initialize the `LibreTranslateAPI` client, translate text, detect language, and list supported languages. It highlights the use of environment variables for configuring the server URL and API key, which is crucial for interacting with public LibreTranslate instances that often require authentication.
import os
from libretranslatepy import LibreTranslateAPI
# Configure LibreTranslate server URL and optional API Key
# For public instances like libretranslate.com, an API key is often required.
# For a self-hosted instance, an API key might be optional depending on server configuration.
LIBRETRANSLATE_URL = os.environ.get('LIBRETRANSLATE_URL', 'https://libretranslate.com/')
LIBRETRANSLATE_API_KEY = os.environ.get('LIBRETRANSLATE_API_KEY', None)
# Initialize the API client
lt = LibreTranslateAPI(LIBRETRANSLATE_URL, api_key=LIBRETRANSLATE_API_KEY)
# Translate text from English to Spanish
text_to_translate = "Hello, how are you?"
source_lang = "en"
target_lang = "es"
try:
translated_text = lt.translate(text_to_translate, source_lang, target_lang)
print(f"Original ({source_lang}): {text_to_translate}")
print(f"Translated ({target_lang}): {translated_text}")
# Detect language
detection_result = lt.detect("Hola mundo")
print(f"Detected language for 'Hola mundo': {detection_result}")
# List available languages
languages = lt.languages()
# print(f"Available languages: {languages}") # Uncomment to see all
print(f"Number of available languages: {len(languages)}")
except Exception as e:
print(f"An error occurred: {e}")
if 'HTTP Error 403: Forbidden' in str(e) or 'HTTP Error 400: Bad Request' in str(e):
print("\nHint: Public LibreTranslate instances often require an API key.")
print("Set the LIBRETRANSLATE_API_KEY environment variable or ensure your server doesn't require one.")
Debug
Known issues
gotchaPublic LibreTranslate instances (e.g., `libretranslate.com`) often require an API key for translation requests, which may not be immediately obvious. Without a valid key, requests can result in HTTP errors like `403 Forbidden` or `400 Bad Request`.fixObtain an API key from a managed LibreTranslate service or ensure you are connecting to a self-hosted instance configured not to require an API key. Pass the key to the `LibreTranslateAPI` constructor using the `api_key` argument, preferably via an environment variable.
affects: All versions
gotcha`libretranslatepy` is a client library only. It does not include a LibreTranslate server. To perform translations, you must have access to a running LibreTranslate server instance, either self-hosted or a public one. Attempting to use the library without a reachable server will result in connection errors.fixEnsure a LibreTranslate server is running and accessible at the URL provided to `LibreTranslateAPI`. If self-hosting, follow the LibreTranslate server installation guides. If using a public instance, verify its uptime and accessibility.
affects: All versions
gotchaTranslation quality can vary, and the underlying LibreTranslate models might occasionally return the original input, a partial translation, or corrupted text if specific language models are missing, faulty, or if the input contains complex structures (e.g., specific HTML, long numerical sequences, or placeholders). This can happen without explicit error messages from the API.fixImplement client-side validation on translated output (e.g., checking for character set changes, length differences, or known placeholder integrity). Ensure your LibreTranslate server has up-to-date and appropriate language models installed for your desired language pairs. Consider pre-processing text to handle sensitive elements (like HTML tags) before sending to the API.
affects: All versions
deprecatedWhile `libretranslatepy`'s `setup.py` declares compatibility with Python `>=2.6`, Python 2.x is officially End-of-Life and is not supported by the core LibreTranslate server project (which requires Python `>=3.8`). Using `libretranslatepy` with Python 2.x is highly discouraged and likely to lead to compatibility issues or unsupported behavior with modern LibreTranslate servers.fixAlways use Python 3.8 or newer for development and deployment involving `libretranslatepy` to ensure compatibility and leverage ongoing community support.
affects: <=2.1.4 (and potentially future versions if `python_requires` is not updated)
Errors
Common errors & fixes
urllib.error.HTTPError: HTTP Error 400: Bad Request
The LibreTranslate server is either inaccessible, requires an API key that was not provided, or the request itself is malformed. This commonly occurs when using public LibreTranslate instances without an API key or when the server address is incorrect.
fixEnsure the LibreTranslate server URL is correct and accessible. If using a public instance (e.g., libretranslate.com), obtain and provide a valid API key during initialization: `lt = LibreTranslateAPI('https://translate.terraprint.co/', api_key='YOUR_API_KEY')`. URLError(ConnectionRefusedError(111, 'Connection refused'))
The Python client failed to connect to the LibreTranslate server, indicating the server is likely not running, is configured on a different port, or a firewall is blocking the connection.
fixVerify that the LibreTranslate server is running on the specified URL and port. Check your firewall settings to ensure that the client can reach the server's port (default 5000).
ERROR: Could not find a version that satisfies the requirement polyglot==X.Y.Z (from libretranslate)
This error often occurs when attempting to install the `libretranslate` *server* package directly via `pip` on platforms like Windows, due to complex underlying dependencies such as `pyicu` or `polyglot` which may lack pre-compiled wheels for your system or Python version. It can also be a confusion between the `libretranslate` server package and the `libretranslatepy` client library.
fixIf you intend to use the Python client library to connect to an *existing* LibreTranslate server, install `libretranslatepy` instead: `pip install libretranslatepy`. If you genuinely want to run the LibreTranslate server, consider using Docker for an easier setup, which handles these dependencies within its container.
ModuleNotFoundError: No module named 'libretranslatepy'
The `libretranslatepy` package has not been installed in the current Python environment, or there is a typo in the import statement.
fixInstall the library using pip: `pip install libretranslatepy`. Ensure your import statement is correct: `from libretranslatepy import LibreTranslateAPI`.
The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application.
This message indicates a server-side issue within the self-hosted LibreTranslate instance, often due to misconfiguration (e.g., Gunicorn worker limits), insufficient system resources, or problems with the underlying `argostranslate` engine or language models.
fixAccess the logs of your LibreTranslate server for more specific error details. Common solutions include adjusting Gunicorn worker/thread settings, ensuring all required language models are correctly downloaded and available, and verifying the server has sufficient CPU and RAM.
Upgrade
Version history
2.1.4latest on PyPI · released Apr 16, 2024
Audit
Dependencies
No dependency data recorded yet.