{"id":6702,"library":"libretranslatepy","title":"LibreTranslate Python Bindings","description":"libretranslatepy provides Python bindings for the LibreTranslate API, a free and open-source machine translation API. It allows Python applications to interact with a LibreTranslate server for translation, language detection, and language listing. The library is currently at version 2.1.4, released in April 2024, and is actively maintained as a client for the continuously developed LibreTranslate ecosystem.","status":"active","version":"2.1.4","language":"python","source_language":"en","source_url":"https://github.com/argosopentech/LibreTranslate-py/","tags":["translation","API client","natural language processing","open-source"],"install":[{"cmd":"pip install libretranslatepy","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"LibreTranslateAPI","correct":"from libretranslatepy import LibreTranslateAPI"}],"quickstart":{"code":"import os\nfrom libretranslatepy import LibreTranslateAPI\n\n# Configure LibreTranslate server URL and optional API Key\n# For public instances like libretranslate.com, an API key is often required.\n# For a self-hosted instance, an API key might be optional depending on server configuration.\nLIBRETRANSLATE_URL = os.environ.get('LIBRETRANSLATE_URL', 'https://libretranslate.com/')\nLIBRETRANSLATE_API_KEY = os.environ.get('LIBRETRANSLATE_API_KEY', None)\n\n# Initialize the API client\nlt = LibreTranslateAPI(LIBRETRANSLATE_URL, api_key=LIBRETRANSLATE_API_KEY)\n\n# Translate text from English to Spanish\ntext_to_translate = \"Hello, how are you?\"\nsource_lang = \"en\"\ntarget_lang = \"es\"\n\ntry:\n    translated_text = lt.translate(text_to_translate, source_lang, target_lang)\n    print(f\"Original ({source_lang}): {text_to_translate}\")\n    print(f\"Translated ({target_lang}): {translated_text}\")\n\n    # Detect language\n    detection_result = lt.detect(\"Hola mundo\")\n    print(f\"Detected language for 'Hola mundo': {detection_result}\")\n\n    # List available languages\n    languages = lt.languages()\n    # print(f\"Available languages: {languages}\") # Uncomment to see all\n    print(f\"Number of available languages: {len(languages)}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    if 'HTTP Error 403: Forbidden' in str(e) or 'HTTP Error 400: Bad Request' in str(e):\n        print(\"\\nHint: Public LibreTranslate instances often require an API key.\")\n        print(\"Set the LIBRETRANSLATE_API_KEY environment variable or ensure your server doesn't require one.\")","lang":"python","description":"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."},"warnings":[{"fix":"Obtain 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.","message":"Public 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement 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.","message":"Translation 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use Python 3.8 or newer for development and deployment involving `libretranslatepy` to ensure compatibility and leverage ongoing community support.","message":"While `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.","severity":"deprecated","affected_versions":"<=2.1.4 (and potentially future versions if `python_requires` is not updated)"}],"env_vars":null,"search_vec":"'2.1.4':44 '2024':48 'activ':51 'allow':22 'api':11,20,63 'applic':24 'april':47 'bind':3,7 'client':55,64 'continu':58 'current':41 'detect':34 'develop':59 'ecosystem':61 'free':13 'interact':26 'languag':33,36,66 'librari':39 'libretransl':1,10,29,60 'libretranslatepi':4 'list':37 'machin':18 'maintain':52 'natur':65 'open':16,69 'open-sourc':15,68 'process':67 'provid':5 'python':2,6,23 'releas':45 'server':30 'sourc':17,70 'translat':19,32,62 'version':43","created_at":"2026-04-15T18:39:17.122923+00:00","updated_at":"2026-04-16T16:12:56.136565+00:00","problems":[{"fix":"Ensure 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')`.","cause":"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.","error":"urllib.error.HTTPError: HTTP Error 400: Bad Request"},{"fix":"Verify 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).","cause":"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.","error":"URLError(ConnectionRefusedError(111, 'Connection refused'))"},{"fix":"If 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.","cause":"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.","error":"ERROR: Could not find a version that satisfies the requirement polyglot==X.Y.Z (from libretranslate)"},{"fix":"Install the library using pip: `pip install libretranslatepy`. Ensure your import statement is correct: `from libretranslatepy import LibreTranslateAPI`.","cause":"The `libretranslatepy` package has not been installed in the current Python environment, or there is a typo in the import statement.","error":"ModuleNotFoundError: No module named 'libretranslatepy'"},{"fix":"Access 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.","cause":"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.","error":"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."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.1.4","cli_name":"","cli_version":null,"type":"library","homepage":"https://libretranslate.com","github":"https://github.com/argosopentech/LibreTranslate-py","docs":null,"changelog":null,"pypi":"https://pypi.org/project/libretranslatepy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["llm-agents","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}