System packages

Step 1. Find out which package you need

A missing system package usually shows up as an error in your publish log or your app's logs. Match your error to a row below.

For OpenCV, try opencv-python-headless in requirements.txt first. It needs no system packages. Our post How to Install System Packages for a Python App explains each package in this table, with code you can test.

Step 2. Find the exact package name

Your app runs on Debian 13, also called trixie. It is the system behind the official Python images. Package names differ between Linux systems, so a name from an Ubuntu, Alpine or macOS guide may not work.

1. Read the install section of the library's own docs. Copy the names after apt install or apt-get install.
2. Check each name on packages.debian.org/trixie.
3. If an error names a missing file, such as libGL.so.1, use the "search the contents of packages" form on the same site. It shows which package contains that file.

Names that end in -dev are for compiling code. You need them only when pip builds a library from source. A library installed from a ready-made wheel needs only the package without -dev.

Step 3. Create packages.txt

Create a plain text file named packages.txt in the same folder as your requirements.txt. If your app sits in a subfolder of your project, put the file in that subfolder. Write one package name per line.

# Convert uploaded audio to MP3, for pydub
ffmpeg
# Read text in scanned receipts, for pytesseract
tesseract-ocr
tesseract-ocr-deu

• Lines that start with # are comments. Text after a # on any line is skipped too.
• Names may contain lowercase letters, numbers, +, - and . only.
• A name listed twice is installed once.
• A file named apt.txt works the same way. If you have both files, Cloudilio installs the packages from both.
• Streamlit Community Cloud uses the same packages.txt format, so files from there work unchanged.

Step 4. Try it in a preview, then publish

Publish a new version the way you normally do. To test without touching your live site, start a preview first. A preview builds the app the same way a publish does.

Open the publish log. Near the start of the build, you will see a line that lists your packages.

Installing system packages: ffmpeg, tesseract-ocr, tesseract-ocr-deu

Cloudilio installs system packages before your Python packages. A library that compiles against a system package while pip installs it, such as mysqlclient, finds it ready.

Step 5. Check that the program works

Add a quick check to your app's startup or a scheduled task you can run with Run now. This code prints where each program is installed, or None if it is missing.

import shutil

for program in ["ffmpeg", "tesseract"]:
    print(program, shutil.which(program))