Getting nanopb onto your machine is refreshingly low drama. There is no installer wizard, no license server, and no giant SDK download. You grab a small archive or a Python package, and ten minutes later you can generate C code from your first .proto file. This guide walks you through every sensible way to install nanopb: the official source archives from GitHub, the generator packages that bundle protoc for you, the pip route for the generator, and the packaged versions for Arduino, PlatformIO, Zephyr, and ESP-IDF. Pick the path that matches your project and follow it through, then run the quick sanity check at the end so you know your nanopb setup actually works.
What you are actually installing
Nanopb has two halves, and keeping them straight saves confusion later. The first half is the runtime: a few small C files, pb_encode.c, pb_decode.c, pb_common.c, and their headers. These files get copied or referenced into your firmware project and compiled with the rest of your code. There is nothing to install system wide for the runtime; it simply lives in your project like any other source file.
The second half is the generator, the tool that turns .proto files into .pb.c and .pb.h files. The generator is a plugin for protoc, Google’s protocol buffer compiler, and it is written in Python. The generator runs on your development machine, never on the microcontroller. When people say they installed nanopb, they usually mean they set up the generator and dropped the runtime files into a project template.
Option 1: download the official release archives
The most direct route is the releases page of the official GitHub project at github.com/nanopb/nanopb. The current release line is the 0.4 series. You will find two flavors of download there.
- Plain source archives, which contain the runtime C files, the generator source, examples, and documentation. Choose this if you already have protoc on your machine or plan to use pip for the generator.
- Generator packages, which bundle a ready to run generator together with a copy of protoc. These exist mainly for convenience, especially on Windows, where setting up protoc and Python by hand can turn into an afternoon project.
Download the archive, extract it to a permanent folder rather than a downloads directory you clean out monthly, and you are done. Many teams keep the extracted folder inside their project repository or in a shared tools folder so every developer generates code with the same nanopb version.
Option 2: install the generator with pip
If Python is already part of your workflow, installing the nanopb generator through pip is the fastest path. The pip package gives you the generator as a protoc plugin, and you invoke it through protoc in the usual plugin style. This route pairs well with the plain source archive: pip provides the generator, the archive provides the runtime files and examples.
One habit worth building early: pin the version you install. Generated code and runtime files are a matched pair in spirit, and a project that quietly regenerates code with a newer generator than the runtime expects can produce confusing build errors. Write down the nanopb version in your project readme and treat upgrades as a deliberate step, not an accident.
Option 3: use the package for your embedded ecosystem
If your project already lives inside an embedded framework, you can often skip manual downloads entirely, because nanopb is packaged for the major ecosystems.
- Arduino users can install nanopb as a library straight from the Arduino Library Manager.
- PlatformIO users can add the nanopb library to their platformio.ini like any other dependency.
- Zephyr projects can pull nanopb in as a Zephyr module.
- ESP-IDF projects can add nanopb as an ESP-IDF component.
These packages handle the runtime files for you and usually wire up the generator as part of the build. That integration is a genuine time saver, because regenerating message code whenever the .proto file changes is exactly the kind of step humans forget.
Add the runtime to a plain C project
Working outside a framework? The manual setup is still simple. Copy pb_encode.c, pb_decode.c, and pb_common.c into your project, along with pb.h, pb_encode.h, pb_decode.h, and pb_common.h. Add the folder to your include path, compile the three .c files with your firmware, and the nanopb runtime is available everywhere. There are no external dependencies to resolve and no configuration step. When you generate message code later, the resulting .pb.c and .pb.h files join the same build.
Sanity check: generate and build something tiny
Do not trust an install you have not exercised. Write a three line .proto file with a small message, for example a SensorMessage with a device id, a temperature, and a label. Add a .options file that gives the label a max_size, then run the generator. You should get a .pb.c and .pb.h pair without errors. Drop them into a test project with the runtime files, encode the message into a buffer with pb_encode(), decode it back with pb_decode(), and print the result. If the values survive the round trip, your nanopb installation is healthy and you can move on to real messages.
A note on versions
Stick with the 0.4 series for new work and keep your generator and runtime from the same release. Nanopb is mature, conservative software, and upgrades are rarely dramatic, but matching versions removes an entire category of weird mismatches between generated code and the runtime that consumes it. If a build error ever mentions fields or macros you do not recognize, a mixed version pairing is the first thing to check.
What is inside the download, and what to keep
When you extract a release archive, you will find more than the bare minimum, and it helps to know which parts matter. The runtime folder holds the three .c files and headers your firmware needs. The generator folder holds the Python plugin and its supporting modules. Around them sit examples showing complete round trips from .proto file to running code, tests that demonstrate edge cases, and documentation that rewards a skim before your first real project.
Keep the whole archive intact in your tools folder even though your firmware only compiles a handful of files. When a build error mentions something unfamiliar, the bundled examples are the fastest reference you own, because they run against the exact version you downloaded. Teams that vendor nanopb into their repository usually check in the runtime files and the generator together, pinned to one release, so a fresh clone of the project can regenerate message code on any machine without hunting the internet for matching pieces.
Conclusion
Installing nanopb is mostly a matter of choosing your lane: release archives for full control, generator packages for a painless Windows setup, pip for Python friendly workflows, or the built in package for Arduino, PlatformIO, Zephyr, and ESP-IDF. Whichever route you take, finish with the round trip sanity check so you know the generator and runtime cooperate. From there, the interesting work begins: designing good .proto files and generating code from them.
Read next:
Pingback: How to Use Nanopb with Arduino and ESP32