Install & Compatibility
Where this runs
tested against v1.11.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
py 3.10
✕ build_error
✓ 88.48s
py 3.11
✕ build_error
✓ 84.58s
py 3.12
✕ build_error
✓ 78.2s
py 3.13
✕ build_error
✓ 78.65s
py 3.9
✕ build_error
✕ build_error
5299MB installed
● package 5299MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
package
✓ import argostranslate.package
✗ from argostranslate import package
While 'from argostranslate import package' might work, the documentation and examples consistently use the fully qualified 'import argostranslate.package' and 'import argostranslate.translate' to avoid name collisions and for clarity.
translate
✓ import argostranslate.translate
✗ from argostranslate import translate
See note for 'package' import.
This quickstart demonstrates how to programmatically download and install a language model, then use it to translate text. The library requires explicit installation of language models (e.g., 'en' to 'es') after the main library itself is installed.
import argostranslate.package
import argostranslate.translate
# Define source and target languages using ISO 639-1 codes
from_code = "en"
to_code = "es"
# Update package index and download/install the desired language model
print("Updating package index...")
argostranslate.package.update_package_index()
available_packages = argostranslate.package.get_available_packages()
package_to_install = next(
filter(
lambda x: x.from_code == from_code and x.to_code == to_code,
available_packages
),
None
)
if package_to_install:
print(f"Downloading and installing {from_code} -> {to_code} package...")
download_path = package_to_install.download()
argostranslate.package.install_from_path(download_path)
print("Package installed.")
else:
print(f"No package found for {from_code} -> {to_code}. Please check available packages or codes.")
# Perform translation
installed_languages = argostranslate.translate.get_installed_languages()
from_lang = next(filter(lambda x: x.code == from_code, installed_languages), None)
to_lang = next(filter(lambda x: x.code == to_code, installed_languages), None)
if from_lang and to_lang:
print(f"Translating 'Hello World' from {from_code} to {to_code}...")
translatedText = from_lang.get_translation(to_lang).translate("Hello World")
print(f"Translated text: {translatedText}")
else:
print("Source or target language not found among installed languages.")
argos-translate --version
Debug
Known issues
breakingMajor breaking changes occurred around versions 1.2 and 1.4, specifically deprecating `load_available_packages` for `get_available_packages` and `load_installed_languages` for `get_installed_languages`. Other changes affected `translate.apply_packaged_translation`, `ITranslate.split_into_paragraphs`, and `package.Package.remove`.fixRefer to the official documentation or GitHub release notes for specific API changes. Update deprecated function calls to their newer equivalents (e.g., `get_available_packages()` instead of `load_available_packages()`).
affects: 1.2, 1.4
gotchaRepeated calls to `argostranslate.translate.translate()` within a loop can be inefficient due to models potentially being reloaded. It's more performant to load the translation object once and reuse it.fixInstead of `argostranslate.translate.translate(text, from_code, to_code)` in a loop, load the `ITranslation` object once: `installed_languages = argostranslate.translate.get_installed_languages(); from_lang = ...; to_lang = ...; translation_obj = from_lang.get_translation(to_lang);` Then, call `translated_text = translation_obj.translate(text)` repeatedly.
affects: All versions
gotchaInstallation issues on Python 3.12 have been reported, primarily due to underlying dependencies like `ctranslate2` or `sentencepiece` not having readily available wheels or requiring specific build environments for Python 3.12 at the time of the issue.fixEnsure you are using the latest `argostranslate` version and `pip`. If issues persist, consider using a slightly older Python version (e.g., 3.11) or checking the `ctranslate2` and `sentencepiece` project pages for Python 3.12 compatibility updates.
affects: >=3.12 (specifically early 3.12 releases)
Errors
Common errors & fixes
Package not found for translating from 'en' to 'es'.
The core `argostranslate` library is installed, but the specific language model package (e.g., English to Spanish) has not been downloaded and installed.
fixYou must explicitly download and install language models. Use `argostranslate.package.update_package_index()` to get available packages, then filter and install the desired one using `argostranslate.package.install_from_path(package_to_install.download())`. Alternatively, use the `argospm` command-line tool: `argospm install translate-en_es`.
'argos-translate' is not recognized as an internal or external command, operable program or batch file.
The `argos-translate` or `argos-translate-gui` executables are not in your system's PATH, or they are not correctly linked/aliased after installation.
fixEnsure that the directory where `pip` installs executables (often `~/.local/bin` on Linux/macOS, or `Scripts` subdirectory in your Python installation on Windows) is included in your system's PATH environment variable. Using a Python virtual environment and activating it can help manage this. On Windows, you might need to invoke it via `python -m argostranslate.cli` or specify the full path to the script.
FileNotFoundError: [WinError 2] The system cannot find the file specified
This error can occur during installation or execution, often related to underlying C++ dependencies (like `ctranslate2` needing a specific compiler or runtime, or `sentencepiece` build issues) or missing system-level tools.
fixEnsure you have the necessary build tools for Python packages (e.g., Microsoft C++ Build Tools on Windows). If using a specific Python version (like 3.12), verify compatibility for `ctranslate2` and `sentencepiece`. A clean virtual environment can sometimes resolve conflicts.
Upgrade
Version history
1.11.0latest on PyPI · released Feb 2, 2026
Audit
Dependencies
ctranslate2requiredCore neural machine translation engine.
sentencepiecerequiredUsed for tokenization of text.
stanzaoptionalUsed for sentence boundary detection (SBD).