LibTomMath: portable multiple precision integer arithmetic in C

A bignum library with no dependencies beyond C

LibTomMath describes itself as a free open source portable number theoretic multiple precision integer library written entirely in C. That is the whole product, and the phrasing tells you what to expect: portable means the same code compiles on the platforms you care about, number theoretic means the algorithms are the classic ones from that field rather than a set of floating point tricks, and entirely in C means there is no runtime, no allocator of its own and no external library to satisfy.

The audience is narrower than a general purpose math toolkit. If you are writing Python or Java, your runtime already ships arbitrary precision integers and the problem does not exist. If you are writing C, especially C for embedded targets, for a cryptographic implementation, or for a system where pulling in a large dependency is a problem, LibTomMath is the kind of library that fits. The project site is libtom.net, and the GitHub topics list the repository as c, libtommath, math, mpi and multi-precision.

The scale of the codebase is visible in the repository layout. The top level is a long list of files named after the operation they implement, mp_add.c, mp_abs.c, mp_cmp_mag.c, mp_div_2d.c, mp_exptmod.c, mp_exteuclid.c, mp_gcd.c and many more, alongside the public header tommath.h. There are directories for the demo programs, the documentation, an etc directory, a modulemap directory and a logs directory.

One file per operation is an unusual choice for a modern C library and it is worth pausing on what it buys. It keeps each algorithm in one place, makes it easy to see exactly which source files a given feature pulls in, and means a port to a new platform is mostly a matter of getting the arithmetic primitives right in one place rather than in a tangled dependency.

The develop branch is the product; tagged releases are the checkpoints

The branch model is stated directly in the README: the develop branch contains the in development version, and stable releases are tagged. The default branch for the repository is develop, so a plain clone gives you the working version rather than a release.

That distinction matters for anyone building on it. The recent release list shows v1.3.0 on 2024-03-27 and v1.3.1-rc1 on 2024-04-16, with the release candidate trailing the final release by about three weeks. The last push to the repository was on 2026-04-20, which is well after those tags, so the tagged versions and the tip of develop are far apart in time.

There is also a distribution channel that deserves a warning label. The README notes that deb packages of the latest state from the develop branch are sometimes uploaded to packagecloud.io, and immediately adds that those packages should be used with caution and at your own discretion. That is a developer build published as a package, not a supported release. For a library whose whole value proposition is being a dependency you can trust, installing an unreviewed build from a branch defeats the point.

The build badges show that both master and develop are built continuously, on GitHub Actions for the main.yml workflow and on AppVeyor, with separate badge URLs per branch. There is also an ABI Laboratory tracker link for API and ABI changes, which is the kind of record you want for a C library where a struct layout change breaks every consumer that was compiled against the old header.

Building with CMake, and the shared library switch

The README gives a CMake recipe, and it is the shortest path to a working build on GNU Linux.

git clone https://github.com/libtom/libtommath.git
mkdir -p libtommath/build
cd libtommath/build
cmake ..
make -j$(nproc)

The out of source build keeps the generated files out of the checkout, and the parallel make is what you would expect on a multicore machine.

A shared library build is one flag away, as the README puts it.

-DBUILD_SHARED_LIBS=On

For the traditional build there is a plain makefile at the top level, and the README says that along with the usual make, make clean and make install there are several other build targets, with the makefile holding the details. There are also makefiles aimed at specific platforms: makefile.mingw, makefile.msvc, makefile.shared and makefile.unix. For Windows there is a Visual Studio solution, libtommath_VS2008.sln with its project file, which is old but still present in the tree, and a Package.swift file at the top level for Swift Package Manager consumers.

Two constraints are worth stating plainly. The README says building is straightforward for GNU Linux only, with the section on building in the release PDF holding the details. And the project publishes a pkg-config template, libtommath.pc.in, which means the library can be linked through pkg-config on systems that have it. If you need a build on something other than GNU Linux, the makefiles and the CMake path are what you will be adapting.

Differential testing against an independent implementation

The test story is the most interesting part of the README, because it describes a method rather than a test count.

Tests live in the demo directory and can be built in two flavours. One produces a standalone test binary that runs several test routines.

make test

The other is an opponent binary, intended to be run against mtest.

make mtest_opponent

The comparison itself is a pipe between the two.

./mtest/mtest | ./mtest_opponent

The explanation in the README is that mtest creates test vectors using an alternative MPI library, and the test binary consumes those vectors to verify correct behaviour of LibTomMath. This is differential testing, and it is the right way to validate a bignum library, because the reference implementation is written by different people with different algorithm choices.

That approach also defines a constraint. Verifying against an alternative library means the alternative library has to be present and working in your build environment. The repository carries helper.pl and other support scripts, and the demo directory includes a Jenkins randomness source file, s_mp_rand_jenkins.c, alongside test.c, timing.c, shared.c and a Swift test target, so the test harness is a real part of the tree rather than a shell script bolted on.

For a library that will handle key sizes and large modular arithmetic, the existence of a differential test setup is a better signal of care than any number of unit tests.

The documentation is a release PDF, a header, and one retired document

Documentation is the weakest part of this project and the README is refreshingly honest about it.

The main documentation is built from the LaTeX file doc/bn.tex and published as a PDF for each release. The same PDF is produced as a build artifact on every CI run. The section on building is in the release PDF, and the section on building LibTomMath in doc/bn.pdf holds the details for the GNU Linux build.

There is also limited documentation in tommath.h, which is where you look when you want the signature and the contract of a specific function and the release PDF is not open in front of you.

Then there is the document that is gone. The library originally shipped tommath.pdf, describing the goals of the project and many of the algorithms used at the time. The README says it has been removed because it can no longer be built and nobody spent the time to fix and update it. The latest valid update to that document was made in version 0.39, and it is contained within that tarball.

So the practical reading advice is specific rather than general. If you want the algorithms explained, find the 0.39 tarball and read tommath.pdf there. If you want the build instructions, read doc/bn.pdf from the release you are using. If you want a function signature, read tommath.h. What you will not find is a maintained wiki or a rendered API reference site, and the LaTeX source means the PDF is only as good as that source.

The licence is custom, and that is the first thing to check

The licence situation needs attention before anything else. GitHub's licence classifier reports the project as other, a custom licence it cannot match to a standard one, with a LICENSE file at the root of the repository. There is no SPDX identifier and no recognisable standard licence name attached to it.

That is unusual for a widely used library and it puts the burden on the reader. If you are considering LibTomMath for commercial or redistributed work, open the LICENSE file and read it as written, and have someone qualified look at it if your use is sensitive. The points above are facts about the repository, not legal advice about what the terms permit.

The same caution applies to the pre-built packages. The README's own wording for the packagecloud.io debs is that they should be used with caution and at your own discretion, and those packages track the develop branch rather than a release.

On the technical side of adoption, the ABI Laboratory tracker for API and ABI changes is the reference to watch. For a C library, the public header tommath.h defines the types, and any change to a struct or to a function signature is a source and binary compatibility event for every consumer. A project that publishes that tracker is telling you it takes the interface seriously.

Where LibTomMath is the wrong choice

The clearest wrong case is a project that already has arbitrary precision integers available. A Python or JavaScript service does not need a C bignum library, and pulling one in would add a native build step for no reason. Another wrong case is a team that needs a maintained upstream with published security advisories and predictable release cadence, because this project tags rarely, publishes release candidates separately, and pushes development to a branch that changes often.

The second alternative approach is worth spelling out, because it is where a bignum library differs from an ordinary dependency. Instead of installing and linking LibTomMath, you can vendor a subset of the source files. The repository layout makes this unusually practical: each operation is its own mp_*.c file, so the files your code needs can be copied into your tree and compiled directly. The trade is that you take on the maintenance of those files yourself, including the risk that a bug fixed upstream never reaches your copy.

A third consideration is that LibTomMath is an integer library. The description and the topic list both name integer arithmetic and nothing else, and there is no floating point or transcendental function layer in sight. If the real requirement is high precision decimal or floating point work, this library is not the answer, and reaching for it would mean building that layer yourself.

The final constraint is the practical one: the documented build path is GNU Linux, the documentation lives in a PDF rather than in searchable online pages, and the API is documented only in tommath.h. Teams that rely on live API documentation will find this library harder to adopt than one with a hosted reference.

Editorial conclusion

Adopt LibTomMath if you are writing C or C++ that needs arbitrary precision integers, especially cryptographic or embedded work where a small auditable dependency matters more than the features of a larger library. Do not adopt it expecting a conventional licence, because the repository carries a custom LICENSE file that GitHub cannot classify, and read that file before shipping it in a product. Before integrating, check the ABI Laboratory timeline for API and ABI changes against the version you plan to pin, build from a tagged release rather than the develop branch if you want reproducible output, and verify that the operations your code needs are present in tommath.h, since the API documentation is limited to that header and the release PDF.

Frequently asked questions

Official sources

1. Issues
2. libtom/libtommath on GitHub
3. Project website
4. README
5. Releases