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 lazyskyline/tdlib        # Debian, glibc — default
docker pull lazyskyline/tdlib:alpine # Alpine, musl — opt-in

Both variants ship linux/amd64 and linux/arm64.

Compatibility rule: a shared library built against one libc cannot be loaded by a process running on the other. Pick the variant matching your consumer's libc — don't mix glibc and musl in the same image.

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

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

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

Use a directory COPY (/usr/local/lib/), not a wildcard. Docker's COPY de-references symlinks when the source is a glob or a single symlink file, which turns the unversioned libtdjson.so link into a duplicate 33 MB regular file and breaks dlopen("libtdjson.so") on glibc. Copying the directory preserves the symlink and keeps the image small.

Python:

FROM lazyskyline/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 lazyskyline/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 lazyskyline/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 lazyskyline/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"]

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

FROM lazyskyline/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"]

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 lazyskyline/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.

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.

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

Full list: hub.docker.com/r/lazyskyline/tdlib/tags.

# 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).

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.

lazyskyline/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 lazyskyline/tdlib:alpine for the moving Alpine tag, or lazyskyline/tdlib:<version>-alpine for a versioned pin.

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

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