How to Self-Host LibreTranslate in 2026: Models, API Limits and Persistent Data

If you already tried to self-host LibreTranslate, the frustrating state is probably familiar: the UI appears, but models were not downloaded or a requested language pair is unavailable. Recreating the container rarely fixes a disagreement between URLs, state and dependencies.

This walkthrough uses one concrete completion criterion — list installed languages, translate a fixed sentence in both directions and exercise API-key quota and error responses. Every configuration choice is evaluated against that criterion rather than against a green container badge.

Restore LibreTranslate on an empty host

List the state before the first real record is created: downloaded models, API-key database and custom configuration. Mount /home/libretranslate/.local before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Confirm the mount by writing harmless data, replacing LibreTranslate and reading it back.

Snapshots are valuable for quick rollback, but an independent backup is needed when the host or volume disappears. Restore into an empty environment with the pinned image and verify that models and API-key state return and the regression corpus completes with acceptable output. Use persistent volumes and snapshots to keep those two recovery mechanisms distinct.

Ports, processes and private services

Do not let the LibreTranslate image choose production architecture by accident. The image supplies a process on 5000; storage, routing and external requirements still need deliberate lifecycles. The local runtime requirement is model download storage and CPU or GPU appropriate to language pairs. Keep its lifecycle explicit so moving LibreTranslate between hosts does not silently change behavior.

The deployment is ready for deeper testing when it can list installed languages, translate a fixed sentence in both directions and exercise API-key quota and error responses. Follow the transaction in logs and watch loaded language models, CPU inference time, parallel requests and disk consumed by model downloads. Those observations reveal whether the current topology isolates the right component.

Prove the LibreTranslate deployment end to end

A production gate for LibreTranslate should be executable by someone who did not build the deployment. Give that person the pinned version, a non-sensitive test account and this task: list installed languages, translate a fixed sentence in both directions and exercise API-key quota and error responses. If the instructions require undocumented shell access, the service is not yet operationally ready.

Repeat the gate after replacing only the container. Then restore downloaded models, API-key database and custom configuration into blank infrastructure and prove that models and API-key state return and the regression corpus completes with acceptable output. Measure loaded language models, CPU inference time, parallel requests and disk consumed by model downloads during both successful runs; unexpected differences often reveal a missing cache, index, worker or data mount.

Add a failure drill: submit harmless input near the resource or format limit associated with this boundary: models were not downloaded or a requested language pair is unavailable. LibreTranslate should emit a useful error, preserve existing state and recover when the valid condition returns. Save the timestamps and relevant log lines, with secrets redacted. That evidence becomes the reference for the next image or configuration change.

Container settings worth reviewing

Use a command that exposes every important choice. This baseline binds LibreTranslate to host loopback, adds the known data mounts and supplies the first required setting. Confirm the local requirement before exposure: model download storage and CPU or GPU appropriate to language pairs.

docker run -d \
  --name libretranslate \
  --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  -v libretranslate-data:/home/libretranslate/.local \
  -e LT_API_KEYS=true \
  libretranslate/libretranslate:latest

Replace floating tags with a tested version or digest. After startup, inspect docker logs --tail 200 libretranslate and confirm the process listens on 5000. Then execute the LibreTranslate acceptance action; a root-page response cannot prove the full scenario succeeds: list installed languages, translate a fixed sentence in both directions and exercise API-key quota and error responses.

Credentials, roles and exposed surfaces

The application-specific security risk is running an unlimited public API that others can drain. The operational answer is to enable API keys or upstream authentication, rate-limit public callers and install only required language pairs. Finish bootstrap through a restricted route and remove temporary setup access immediately afterward.

LT_API_KEYS controls behavior rather than confidentiality; validate its type and value, and store genuine LibreTranslate credentials separately. Give the LibreTranslate process only its documented mounts and dependency routes; avoid host root and Docker socket access. Log failed authentication and configuration errors, but redact tokens, connection strings and user content.

Keep internal and external URLs straight

TLS issuance is only half of the LibreTranslate route. Serve the API through HTTPS and document the correct base path. Send traffic internally to 5000 and forward the external scheme so generated URLs and secure cookies remain consistent.

Use the complete LibreTranslate scenario from a clean network, not merely the root page. A 502 or certificate failure can be isolated with automatic domain and TLS setup. If traffic reaches the process and models were not downloaded or a requested language pair is unavailable, diagnose that condition where it occurs instead of stacking redirects.

Failure drills for LibreTranslate

Capacity tests should exercise loaded language models, CPU inference time, parallel requests and disk consumed by model downloads, not a repeated request to /. Run the scenario “list installed languages, translate a fixed sentence in both directions and exercise API-key quota and error responses” at realistic concurrency and record latency, error rate and storage growth.

Upgrade planning must account for this risk: model packages and server releases can change translation output, so maintain a small regression corpus. Test the new release with representative input, then repeat the acceptance transaction and compare its result. If models were not downloaded or a requested language pair is unavailable, capture the failing transaction and inspect the first boundary involved instead of assuming ingress is responsible.

Deploy LibreTranslate on Dockup without losing its boundaries

A Dockup template should encode the image, port 5000, mounts, health timing, domain, TLS and secret delivery. Dockup should preserve the LibreTranslate runtime settings while the operator confirms this local requirement: model download storage and CPU or GPU appropriate to language pairs. The same deployment can target Dockup servers or customer-attached capacity.

After the route is live, apply the public setting and try to list installed languages, translate a fixed sentence in both directions and exercise API-key quota and error responses. Back up downloaded models, API-key database and custom configuration and keep the restore exercise in the operating plan; those are LibreTranslate responsibilities that remain visible after infrastructure provisioning.

Frequently asked questions

What does LibreTranslate need for a production deployment?

Route the LibreTranslate container on port 5000 through one HTTPS origin. The local runtime requirement is model download storage and CPU or GPU appropriate to language pairs. Do not call LibreTranslate ready until you can list installed languages, translate a fixed sentence in both directions and exercise API-key quota and error responses.

Which LibreTranslate data belongs in a backup?

Persist /home/libretranslate/.local and include downloaded models, API-key database and custom configuration in the same recovery manifest. A clean LibreTranslate restore passes only when models and API-key state return and the regression corpus completes with acceptable output.

Does LibreTranslate require HTTPS behind a reverse proxy?

Use HTTPS for the public LibreTranslate origin and keep port 5000 on the internal route. Apply the LibreTranslate setting correctly: serve the API through HTTPS and document the correct base path. For LibreTranslate, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a LibreTranslate upgrade be tested?

Restore current LibreTranslate state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because model packages and server releases can change translation output, so maintain a small regression corpus. Keep the previous LibreTranslate image until its data-migration and rollback boundary are understood.