hello_tf_c_api: TensorFlow C API Examples You Can Build and Read

What hello_tf_c_api actually solves

The TensorFlow C API is documented thinly compared with the Python surface, and the official guides assume you already know how to wire headers, native libraries and runtime DLLs together. This repository fills that gap with fourteen small example programs and a helper library, all built by one CMake project. The examples run from a hello-world graph load up to batch interfaces, tensor info and graph info.

The audience is narrow and worth naming: C++ engineers who need to call TensorFlow from an existing native application, and who want to read a working call sequence rather than infer it from header files. If you are building a Python service, this repository has nothing for you. The README frames the scope as "a small cross-platform set of TensorFlow C API examples for Windows, Linux, and macOS", and that phrasing is accurate rather than modest. There is no runtime component to deploy, no service to configure and no API surface that changes between versions.

How the CMake build finds TensorFlow

The mechanism is a Python wheel used as a source of headers and native libraries. During CMake configure, the project downloads TensorFlow 2.21.0 from the Python wheel into a build-local cache at `<build>/_deps/tensorflow/python`, then points at the headers under `<TENSORFLOW_ROOT>/python/tensorflow/include` and the libraries under `<TENSORFLOW_ROOT>/python/tensorflow` and `<TENSORFLOW_ROOT>/python/tensorflow/python`. Python with pip is therefore required at configure time, not only at build time. That surprises people who expect a C++ project to have no Python dependency.

The CMake file creates an imported `tensorflow` target and a `hello_tf_utils` helper library target. Examples that use the helper API link `hello_tf_utils`; examples that demonstrate only the raw C API use `target_link_tensorflow(<target>)`. On Windows, the build copies the required TensorFlow runtime DLLs into the build output directories, which removes the most common first-run failure on that platform.

One design point in the helper API is worth reading carefully before you copy it. The README states that `tf_utils::LoadGraph` only imports a GraphDef, and that if a graph needs checkpoint restore operations you must create the session first and then call `tf_utils::RestoreCheckpoint(session, graph, ...)` on that session. The reason given is that TensorFlow variable state belongs to `TF_Session`, not to `TF_Graph`. That is a real constraint of the C API, and the examples encode it rather than hiding it.

Building the examples on Linux, macOS and Windows

The README gives a separate command sequence per platform. On Linux, clone, create a build directory, configure with `-DCMAKE_BUILD_TYPE=Release`, build in parallel and run the tests:

git clone --depth 1 https://github.com/Neargye/hello_tf_c_api
cd hello_tf_c_api
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j 4
ctest --output-on-failure

Configure is the step to watch. It needs Python with pip available, and by default it reaches out to fetch the TensorFlow 2.21.0 wheel. If that download is blocked on your network, configure fails before any compiler runs. The tests use doctest, and CI also runs an ASan/UBSan job on Ubuntu, so the example code is exercised under sanitizers upstream.

On Windows the configure step differs in two ways: the generator architecture must be 64-bit, and the build is multi-config, so the configuration is passed to the build and test commands rather than to configure:

cmake -A x64 ..
cmake --build . --config Release
ctest --output-on-failure -C Release

macOS uses the same configure line as Linux but passes `--config Release` to the build and `-C Release` to ctest, matching the multi-config layout. If you already have a TensorFlow wheel extraction on disk, configure with `-DTENSORFLOW_ROOT=/path/to/tensorflow` to skip the download. The README notes that auto-fetch only writes to the default build-local cache and refuses to overwrite an external `TENSORFLOW_ROOT`; to require a pre-existing extraction and disable downloads entirely during configure, add `-DHELLO_TF_FETCH_TENSORFLOW=OFF`.

A first run that needs no model download

The graph and session examples use a small GraphDef committed as `models/graph.pb`, so a first run does not depend on downloading a model. After the build, the example binaries are the entry point. The repository does not document a single canonical run command per example, so the practical first step is to run the test suite, which exercises the examples, and then run one binary from the build tree.

The helper library is what most readers will actually reuse. Linking it in your own target follows the pattern the README gives for the examples:

target_link_libraries(<target> PRIVATE hello_tf_utils)

If you only want the raw C API without the helper layer, the README gives the other form:

target_link_tensorflow(<target>)

To regenerate the committed GraphDef, the README points at `python tools/create_example_graph.py`, run from a Python environment where the full TensorFlow package is available. That is a build-tooling step, not a runtime requirement.

Two configure flags trim the project down. `-DHELLO_TF_BUILD_EXAMPLES=OFF` configures only the helper library without example executables, and `-DBUILD_TESTING=OFF` configures without tests, since tests follow CMake's standard `BUILD_TESTING` option. OpenCV is optional: if CMake finds it, the OpenCV image-file example is built and tested, and if it does not, that one example is simply absent.

Where this repository is the wrong tool

The README is explicit that this is not a dependency: "This repository is maintained as local examples plus tests, not as a packaged dependency." There are no releases, no package published to a registry, and no versioned ABI to pin. If another project needs a small part of it, the README's own advice is to copy the relevant example or helper source and wire it to that project's TensorFlow target explicitly. That means you inherit the maintenance of whatever you copy, including the `tf_utils::LoadGraph` and `RestoreCheckpoint` split described above.

The second limitation is the Python dependency at configure time. A build machine with no Python and no pip cannot configure this project on the default path, and the auto-fetch writes into the build tree, so a clean rebuild re-fetches unless you point `TENSORFLOW_ROOT` at a persistent extraction. In an offline or air-gapped build, plan for `-DHELLO_TF_FETCH_TENSORFLOW=OFF` plus a pre-staged extraction.

Third, the examples target TensorFlow 2.21.0 specifically. The README also notes that you can build the TensorFlow library version you need from source, with CPU or GPU support, but the CMake path here is written around that wheel. If your deployment pins a different TensorFlow version, the example code is still a useful reference while the build wiring is not reusable as-is. And if your model is a TensorFlow 2 SavedModel rather than a GraphDef, the README's own guidance is to prefer a SavedModel export for your own models, or a small inference-only GraphDef when you want the same import path as the examples.

TensorFlow Lite C++, and linking the C API by hand

The closest alternative in search interest is TensorFlow Lite C++, and the difference is architectural rather than cosmetic. TFLite is built around a flatbuffer model and an interpreter with a deliberately limited operator set, aimed at mobile and embedded deployment. This repository links the full TensorFlow C API from a desktop wheel, so you get the complete runtime, the graph and session model, and checkpoint restore through `TF_Session`. If your target is a phone or a microcontroller, TFLite is the right shape and this project is not. If your target is a desktop or server C++ process that already ships TensorFlow, the opposite holds.

The other alternative is doing the wiring yourself, which the README supports directly. It tells you to use the headers from `<TENSORFLOW_ROOT>/python/tensorflow/include` and the native libraries from `<TENSORFLOW_ROOT>/python/tensorflow` and `<TENSORFLOW_ROOT>/python/tensorflow/python`. It also documents the Visual Studio path: add the TensorFlow include path under C/C++ Additional Include Directories, add the import library path under Linker Additional Dependencies, and make sure the TensorFlow DLLs are in the output directory or somewhere on `%PATH%`. Choosing that route means you get no helper library and no example tests, but also no CMake download step and no Python requirement at configure time. For a team that already has a working TensorFlow build, that is often the shorter path.

Maintenance, licensing and the cost of copying code

The repository is not archived, and the last push was on 2026-07-08. The examples are pinned to TensorFlow 2.21.0, so the upgrade cost is the cost of moving that pin: change the wheel version the CMake configure fetches, or point `TENSORFLOW_ROOT` at a newer extraction, then rebuild and run `ctest`. Because the project is not a packaged dependency, there is no version negotiation to manage, but there is also no upstream signal telling you when the pin is stale. You have to watch the TensorFlow release notes yourself.

Licensing is MIT, which is permissive and places few conditions on reuse. The repository also contains a NOTICE file, and its `test/3rdparty/doctest/doctest.h` is a vendored third-party header, so if you copy test code rather than example code, check that file's own licence terms. This is a description of what the repository states, not legal advice; route the specifics through your own review.

The practical upgrade cost sits with anything you copy. A helper you lift into your own tree stops receiving fixes from this repository the moment you copy it, and the README's guidance to copy rather than depend makes that outcome the expected one rather than an accident.

Editorial conclusion

Adopt hello_tf_c_api if you need a readable, working reference for the raw TensorFlow C API in C++17 and you are willing to copy the helper sources into your own build. Do not adopt it as a library dependency: the README states the repository is maintained as local examples plus tests, not as a packaged dependency. Before committing, verify that CMake configure succeeds with Python and pip present, because the default path downloads TensorFlow 2.21.0 into <build>/_deps/tensorflow/python, and check whether your target platform is 64-bit, since the requirements list a 64-bit target.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Neargye/hello_tf_c_api on GitHub
4. README