Install & Compatibility
Where this runs
tested against v4.8.1 · 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
no_wheel
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 5.1s · import 0.638s · 221MB
226MB installed
● package 226MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Translator
✓ from ctranslate2 import Translator
✗ import ctranslate2
translator = ctranslate2.Translator(model_path)
This quickstart demonstrates how to load a pre-converted model using `ctranslate2.Translator` and perform a basic text translation. It assumes a model has already been converted (e.g., from Hugging Face Transformers) and a tokenizer is available. For generation tasks, use `ctranslate2.Generator` instead.
# First, convert a model. This example uses a Hugging Face model.
# You would run this command in your terminal once:
# pip install transformers[torch]
# ct2-transformers-converter --model Helsinki-NLP/opus-mt-en-de --output_dir opus-mt-en-de
import ctranslate2
import transformers
# Path to your converted CTranslate2 model directory
model_path = "opus-mt-en-de"
try:
# Initialize the CTranslate2 Translator
translator = ctranslate2.Translator(model_path, device="cpu") # Use device="cuda" for GPU
# Initialize the original tokenizer (e.g., from Hugging Face for tokenization)
tokenizer = transformers.AutoTokenizer.from_pretrained("Helsinki-NLP/opus-mt-en-de")
text_to_translate = "Hello world!"
# Encode the input text to tokens
input_tokens = tokenizer.convert_ids_to_tokens(tokenizer.encode(text_to_translate))
# CTranslate2 expects a batch of inputs, so wrap in a list
batch_inputs = [input_tokens]
# Perform translation
results = translator.translate_batch(batch_inputs)
# Decode the output tokens
output_tokens = results[0].hypotheses[0]
translated_text = tokenizer.decode(tokenizer.convert_tokens_to_ids(output_tokens))
print(f"Original: {text_to_translate}")
print(f"Translated: {translated_text}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure you have a model converted and located at 'opus-mt-en-de' ")
print("and that 'transformers' library is installed.")
print("For example, you can run: `pip install transformers[torch]` and then ")
print("`ct2-transformers-converter --model Helsinki-NLP/opus-mt-en-de --output_dir opus-mt-en-de`")
ct2-transformers-converter --version
Upgrade
Version history
4.8.1latest on PyPI · released Jul 3, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or higher.
sentencepieceoptionalCommonly used for tokenization with CTranslate2 models (e.g., OpenNMT, OPUS-MT).
transformersoptionalRequired for converting models from the Hugging Face Transformers library to CTranslate2 format.
OpenNMT-pyoptionalRequired for converting models trained with OpenNMT-py to CTranslate2 format.
torchoptionalNeeded for AMD GPU support with ROCm, PyTorch 2.1+ required. Also often used for model conversion workflows.
cudaoptionalNVIDIA CUDA Toolkit (12.x recommended) is required for NVIDIA GPU acceleration.
cudnnoptionalNVIDIA cuDNN (8 or 9, depending on CTranslate2 version) is recommended for optimal performance with convolutional layers on NVIDIA GPUs.
rocmoptionalAMD ROCm (6.0+) is required for AMD GPU acceleration.