TDLib (tdlib/td): building a Telegram client on top of a C++ library

What TDLib takes off your plate, and who it is aimed at

Writing a Telegram client from scratch means implementing MTProto, managing an encrypted local store, and keeping update ordering correct across a flaky connection. TDLib is the library that already does that work. The README describes it as a cross-platform library for building Telegram clients, and lists the responsibilities it absorbs: network implementation details, encryption and local data storage. That framing tells you who it is for. It is for people shipping an actual Telegram client, not for someone who wants to send a message from a script.

The distinction matters because a large share of Telegram automation does not need TDLib at all. If your use case is a bot that responds to commands, the Telegram Bot API is a plain HTTP surface and TDLib is the wrong tool. TDLib is for the cases where a bot API will not do: logging in as a user, reading message history, managing chats, or building an app that behaves like the official clients. The README positions the library around those client-level concerns rather than around convenience wrappers.

How TDLib is structured: a C++ core with generated bindings on top

The repository layout shows a C++ core split across several directories: td/ for the Telegram logic, tdnet/ for networking, tdutils/ for utilities, tddb/ for the database layer, tdactor/ for the actor model, and tdtl/ for the TL serialization machinery. A separate sqlite/ directory and a top-level SplitSource.php script sit alongside them. This is not a thin wrapper around an HTTP endpoint. It is an implementation of the protocol with its own storage and concurrency model.

The API surface is generated. The README points to td/generate/scheme/td_api.tl as the scheme and to automatically generated HTML documentation for the full list of methods and classes. That is the mechanism behind the claim that TDLib is usable from almost any language: the same scheme produces a C++ interface, a JSON interface, Java bindings through JNI, and .NET bindings through C++/CLI and C++/CX. The JSON interface is described as having a simple C interface, which is what makes it callable from languages that can execute C functions but have no TDLib binding of their own.

The README also states a consistency guarantee that shapes how you write code against it: all updates are delivered in the right order. Combined with the fully-asynchronous design, where requests do not block each other and responses arrive when available, you end up with an event-driven programming model rather than a request-response one. If you are used to calling a method and getting a value back, the adjustment is real.

Building TDLib from source with CMake

There is no package-manager install line in the README. The stated simplest path is the TDLib build instructions generator at tdlib.github.io/td/build.html, where you pick a language and target operating system and receive build instructions. The generic CMake sequence is given directly in the README and requires the dependencies to be present first: a C++17 compiler, OpenSSL, zlib, gperf for the build, and CMake 3.10 or later.

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

After this you have the built libraries. To consume them from a CMake C++ project, the README gives two approaches. You can add the source tree as a subdirectory and link a target, or install TDLib and find it by package name.

add_subdirectory(td)
target_link_libraries(YourTarget PRIVATE Td::TdStatic)

find_package(Td 1.8.67 REQUIRED)
target_link_libraries(YourTarget PRIVATE Td::TdStatic)

The three targets the README names are Td::TdJson and Td::TdJsonStatic for the JSON interface, and Td::TdStatic for the C++ interface. Choosing between them is the first real decision: the JSON interface is the one that travels to other languages, while the C++ interface is for C++ projects that want the ClientManager and Client classes directly. For Java, the README says to pass -DTD_ENABLE_JNI=ON to CMake, and for .NET, -DTD_ENABLE_DOTNET=ON or -DTD_ENABLE_DOTNET=CX. The example/ directory holds per-language samples for android, cpp, csharp, ios, java, python, swift, uwp and web.

The build is the hard part, and low-memory machines feel it first

TDLib is a large C++ codebase, and the README acknowledges the consequence directly by documenting a workaround for constrained hardware. Before compiling, you can run the SplitSource.php script to break sources into smaller units, build only the targets you need, then undo the split.

php SplitSource.php
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --target tdjson
cmake --build . --target tdjson_static
cd ..
php SplitSource.php --undo

The README reports that in the project's own tests clang 6.0 with libc++ needed less than 500 MB of RAM per file and GCC 4.9/6.3 needed less than 1 GB per file. Those are the project's figures for its own test setup, not a promise about your machine, but they set expectations: this is a build that wants memory. Note also that the split workflow depends on PHP being available. The dependency list marks PHP as optional and for documentation generation, but SplitSource.php is a PHP script, so the low-memory path is not PHP-free in practice. That is a small documentation gap worth knowing before you start.

A second practical constraint is the .NET route. The README states that .NET Core supports C++/CLI only since version 3.1 and only on Windows, so if you are on an older .NET Core or need portability, the guidance is to use the JSON interface through P/Invoke instead. It also warns that when TD_ENABLE_DOTNET is enabled, C++ documentation is removed from some files, and lists the files to check out to restore it. These are the kinds of details that decide whether a binding is viable for your platform, and they are documented rather than hidden.

Where TDLib is the wrong choice

The clearest boundary is the one the README implies rather than states: TDLib is a client library, so if you are building a bot, reach for the Bot API first. A bot that answers a few commands does not justify compiling a C++ library, and the maintenance burden of tracking a source-built dependency is not repaid by features you will not use.

The second boundary is language and build environment. TDLib is usable from almost any language that can execute C functions, but usable is doing a lot of work in that sentence. You still need to build the native library for each platform you ship, and you still need to marshal the JSON interface or write a binding. A team with no C++ build experience and no appetite for maintaining one should treat that as a genuine cost, not a footnote. The README's own framing, that the simplest way to build is to use the generator, is an acknowledgement that manual builds are fiddly enough to warrant a guided tool.

The third is the asynchronous model. The README states that requests do not block and responses arrive when available, and that updates are ordered. If your application architecture assumes synchronous calls, you will be writing state machines around TDLib rather than calling functions. That is inherent to a library that stays stable on slow and unreliable connections, but it is a design commitment you inherit.

TDLib against the Telegram Bot API

The alternative most readers will actually weigh is the Telegram Bot API, which the README itself references when discussing performance. The difference in approach is fundamental. The Bot API is an HTTP interface: you send a request, you get a response, and Telegram runs the client for you. TDLib is the client. You embed it, it holds the connection, it encrypts and stores local data with a user-provided encryption key, and it delivers updates in order.

That difference decides the choice. The Bot API cannot log in as a user, so anything requiring a user account is out of its reach. TDLib can, at the cost of managing sessions, storage and encryption yourself. The README's performance claim sits on the Bot API side of this comparison: it states that in the Telegram Bot API, each TDLib instance handles more than 43000 active bots simultaneously. That is the project's own figure describing a deployment where TDLib backs a bot service, and it is a useful illustration of where the library is used even when the visible interface is the Bot API.

A second alternative is simply using an existing client library in your language rather than binding TDLib yourself. The README points to example/python and example/swift among others, and to native Java and .NET bindings, which tells you the project expects most users to start from a language-specific example rather than from the raw C interface.

Licence and the cost of tracking upstream

TDLib is released under the Boost Software License 1.0, with the text in LICENSE_1_0.txt at the repository root. BSL-1.0 is a permissive licence, which in practice means it does not carry the copyleft obligations that would force you to publish your own client's source. This is a description of the licence identifier, not legal advice; read the file and involve counsel if your distribution model is unusual.

On maintenance, the repository is not archived and the last push was on 2026-09-21. The README does not document a release cadence or a support window, and no recent releases were retrieved, so the practical upgrade signal is the commit history and CHANGELOG.md rather than tagged versions. The README does show one version-sensitive detail: the find_package example pins Td 1.8.67, which suggests versioned consumption is expected. If you depend on the generated API, budget for the fact that td_api.tl can change and that regenerating bindings is part of upgrading. The README does not document rollback or a compatibility policy for the generated interface, so treat that as something to establish yourself before you ship.

Editorial conclusion

Adopt TDLib if you are writing a Telegram client and want the protocol, encryption and local storage handled for you, and you accept a CMake build with OpenSSL, zlib and gperf as prerequisites. Do not adopt it if you only need to call a handful of bot methods, because the Telegram Bot API covers that with an HTTP request instead of a build. Before committing, verify the CMake target you intend to link against (Td::TdJson, Td::TdJsonStatic or Td::TdStatic), confirm your compiler meets the C++17 requirement the README states, and read the licence text in LICENSE_1_0.txt, since the Boost Software License 1.0 governs what you may redistribute.

Frequently asked questions

Official sources

1. Issues
2. License: BSL-1.0
3. Project website
4. README
5. tdlib/td on GitHub