klhq/tdlib repository overview

⁠TDLib Docker Image

Prebuilt, multi-arch Docker images of TDLib (Telegram Database Library)⁠. Drop libtdjson.so into your bot, client, or service and skip the 30–60 minute TDLib compile.

docker pull klhq/tdlib        # Debian, glibc — default
docker pull klhq/tdlib:alpine # Alpine, musl — opt-in

Both variants ship linux/amd64 and linux/arm64.

⁠Which tag should I pull?

If unsure, pull the default (klhq/tdlib). It works for ~95% of real-world TDLib consumers.

⁠Quick start

Three patterns, in order of how often they're used.

⁠Pattern A — COPY --from into your own image (recommended)

The canonical pattern. Your runtime image stays small; you just lift libtdjson.so.

Python:

FROM klhq/tdlib:latest AS tdlib

FROM python:3.12-slim
COPY --from=tdlib /usr/local/lib/ /usr/local/lib/
RUN ldconfig
RUN pip install --no-cache-dir python-telegram
COPY app.py /app/
WORKDIR /app
CMD ["python", "app.py"]

Node.js:

FROM klhq/tdlib:latest AS tdlib

FROM node:20-slim
COPY --from=tdlib /usr/local/lib/ /usr/local/lib/
RUN ldconfig
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "bot.js"]

Go (cgo bindings):

FROM klhq/tdlib:latest AS tdlib

FROM golang:1.22-bookworm
COPY --from=tdlib /usr/local/lib/ /usr/local/lib/
RUN ldconfig
WORKDIR /src
COPY . .
RUN go build -o /bot ./cmd/bot
CMD ["/bot"]

Python (Alpine consumer — :alpine variant):

The Alpine image is built with clang/libc++, so Alpine consumers must install those runtime libraries explicitly.

FROM klhq/tdlib:alpine AS tdlib

FROM python:3.12-alpine
RUN apk add --no-cache libssl3 zlib libc++ libgcc llvm-libunwind
COPY --from=tdlib /usr/local/lib/ /usr/local/lib/
RUN pip install --no-cache-dir python-telegram
COPY app.py /app/
WORKDIR /app
CMD ["python", "app.py"]

⁠Pattern B — FROM klhq/tdlib as a base

Simpler when your app is mostly TDLib glue. You inherit Debian + the lib in one shot.

FROM klhq/tdlib:latest
USER root
RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip \
 && rm -rf /var/lib/apt/lists/*
USER app
COPY app.py /app/
CMD ["python3", "/app/app.py"]

⁠Pattern C — Extract libtdjson.so for bare-metal / CI use

Pull the lib out of the image and drop it next to a binary running on a VM, CI runner, or developer laptop.

docker create --name td-extract klhq/tdlib:latest
docker cp td-extract:/usr/local/lib/. ./tdlib-libs/   # trailing /. copies directory contents and preserves symlinks
docker rm td-extract
sudo cp -P ./tdlib-libs/* /usr/local/lib/ && sudo ldconfig

The trailing /. matters: docker cp follows a symlink if you point it at one directly, but copies the symlink-as-symlink when you copy a directory's contents. After installing to /usr/local/lib, cp -P preserves the symlink, and ldconfig registers both libtdjson.so and the versioned SONAME in the loader cache.

The extracted .so is a standard glibc shared library — usable on any modern glibc Linux (Ubuntu 22.04+, Debian 12+, RHEL/Rocky 9+, Arch, Fedora). For Alpine hosts, extract from :alpine instead.

⁠Compatibility matrix

glibc is forward-compatible: the Debian variant (built on bookworm, glibc 2.36) runs anywhere with glibc ≥ 2.36. For older systems (Ubuntu 20.04, RHEL 8), build the image locally on debian:bullseye — see Building locally⁠.

⁠What's inside the image

Both variants link OpenSSL 3 and zlib dynamically. Debug symbols are stripped.

⁠All tags

Full list: hub.docker.com/r/klhq/tdlib/tags⁠.

⁠Building locally

# Debian variant (default)
docker buildx build -f Dockerfile -t tdlib-local .

# Alpine variant
docker buildx build -f Dockerfile.alpine -t tdlib-local-alpine .

# Multi-arch (requires QEMU + buildx setup)
docker buildx build --platform linux/amd64,linux/arm64 -f Dockerfile -t tdlib-local .

To target an older glibc, swap the base images in Dockerfile from bookworm to bullseye (glibc 2.31, covers Ubuntu 20.04).

⁠Versioning

The image version tracks TDLib upstream's version, sourced from CMakeLists.txt⁠ (project(TDLib VERSION X.Y.Z ...)). Releases are tagged on GitHub when upstream cuts a new version; CI then builds and pushes the matching Docker tags.

See GitHub Releases⁠ for per-version changelogs.

⁠Breaking change: default variant is now Debian

klhq/tdlib:latest previously pointed to the Alpine-based (musl) image. It now points to the Debian-based (glibc) variant, which matches the libc of the overwhelming majority of TDLib consumers (Python, Node, Go cgo, Java, Ubuntu/Debian/RHEL hosts).

If you were relying on the Alpine variant, pin to klhq/tdlib:alpine for the moving Alpine tag, or klhq/tdlib:<version>-alpine for a versioned pin.

⁠Resources

• TDLib documentation⁠
• TDLib API reference⁠
• TDLib examples (upstream)⁠
• This repository's source & issues⁠

⁠License

TDLib is licensed under the Boost Software License 1.0⁠. The Docker packaging in this repository is provided under the same license.