LibreTranslate crashed every time I loaded language models

I spun up LibreTranslate in Docker last week because I needed translation in my homelab without sending text to some API. Private. Local. Seemed straightforward. It wasn’t.

The container would start fine. The web interface loaded. Then the moment I tried to translate anything, it would just… stop. No error in the logs. No crash message. Just gone. Docker health check failing, container restart cycle, and me staring at journalctl at 11 PM wondering what I did wrong.

The obvious suspects didn’t pan out

First thing I checked: disk space. I had plenty. Then I looked at the logs more carefully. Actually, I looked at them less carefully — there basically weren’t any. LibreTranslate was starting the translation engine, and then the container was dying silently. That’s an OOM kill, nine times out of ten.

My docker-compose was naive. I’d given the container a 512MB memory limit because I wasn’t thinking. The Argos Translate models are not light. Each language pair model is something like 200-300MB sitting in RAM while it works. The first time LibreTranslate tried to load a model and run a translation, it blew past 512MB and the kernel started arresting processes.

I bumped it to 2GB. Still died. Then 3GB. Kept dying. I started wondering if LibreTranslate itself was just broken, or if my Docker setup was cursed.

The thing that surprised me

I don’t know why I didn’t think of this sooner, but I actually logged into the container and tried to see what was happening in real time. Got a shell open, ran the model download manually, watched top while it happened.

That’s when I saw it: the model was loading, memory was climbing, and then… Docker’s memory limit wasn’t the problem. The problem was that LibreTranslate was trying to load both the source and target language models simultaneously for some reason, and with my default config it was pulling down a ton of extra stuff on initialization. I was also running this on a machine with 8GB total RAM, and I had other containers competing for memory. The pressure was real.

But more importantly: I’d mounted the models directory wrong. LibreTranslate wasn’t persisting the language models between restarts. Every time the container came back up, it was re-downloading and re-initializing everything from scratch. That’s not a memory issue. That’s a design issue meeting a config mistake.

What actually fixed it

Proper volume mounts and sensible resource allocation. Here’s what my docker-compose looks like now:

version: '3.8'
services:
  libretranslate:
    image: libretranslate/libretranslate:latest
    container_name: libretranslate
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - LT_LOAD_ONLY=en,es,fr,de
      - LT_THREADS=4
    volumes:
      - lt_models:/home/libretranslate/.local/share/argos-translate/packages
    mem_limit: 4g
    memswap_limit: 4g
    cpus: 2

volumes:
  lt_models:
    driver: local

Three critical things here: First, the LT_LOAD_ONLY variable. I was letting it load all 30+ language pairs. I only needed English, Spanish, French, and German. This cut initialization time and memory footprint drastically. Second, the volume mount to /home/libretranslate/.local/share/argos-translate/packages persists the models across container restarts. Download them once, they stay downloaded. Third, I gave it 4GB of actual memory and told it to use 4 threads instead of going crazy with parallelism.

After that change, it worked. No crashes. Translations now happen in 200-500ms depending on text length. The container starts in about 10 seconds and doesn’t respawn randomly.

The REST API is straightforward enough — a POST to http://localhost:5000/translate with JSON payload, and you get translated text back. I’ve got it hooked into Node-RED for some automation work, and it’s nice having this running locally where I’m not worried about rate limits or anyone logging what I’m translating.

What really got me was that the failure mode was so quiet. No warning. No graceful degradation. Just the container dying. If you run into the same thing, check your volume mounts first, then your memory allocation, then be aggressive about what language pairs you actually load. LibreTranslate is solid once it’s running, but the first boot is where things get weird.

Explore LibreTranslate in our AI Homelab Toolkit.