Install & Compatibility
Where this runs
tested against v0.4.9.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.8MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.0s · import 0.000s · 21MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nanopb_generator.py (script)
✓ python -m nanopb.generator.nanopb_generator your_message.proto
✗ import nanopb.generator
The primary interaction with the Python library is by executing the `nanopb_generator.py` script, not importing its modules into application code.
This quickstart demonstrates how to define a simple Protocol Buffer message and then use the `nanopb_generator.py` script to generate the corresponding C header and source files for use with the Nanopb C runtime. It assumes `nanopb`, `protobuf`, and `grpcio-tools` are already installed.
# 1. Define your Protocol Buffer message in a .proto file (e.g., example.proto):
# message SimpleMessage {
# required int32 value = 1;
# }
# 2. Run the nanopb generator script:
import subprocess
import os
proto_content = """
syntax = "proto2";
message SimpleMessage {
required int32 value = 1;
}
"""
with open("example.proto", "w") as f:
f.write(proto_content)
# Ensure protobuf and grpcio-tools are installed
try:
import google.protobuf
print("google.protobuf module found.")
except ImportError:
print("google.protobuf not found. Please install with: pip install protobuf grpcio-tools")
exit(1)
# Specify the path to the generator script
# In an installed package, it's usually found via -m
generator_path = "nanopb.generator.nanopb_generator"
print(f"Generating C files from example.proto using {generator_path}...")
try:
# Using python -m for installed package
result = subprocess.run(
["python", "-m", generator_path, "example.proto"],
capture_output=True, text=True, check=True
)
print("STDOUT:", result.stdout)
print("STDERR:", result.stderr)
print("Successfully generated example.pb.h and example.pb.c")
# Verify output files exist (optional)
if os.path.exists("example.pb.h") and os.path.exists("example.pb.c"):
print("Output files example.pb.h and example.pb.c found.")
else:
print("Error: Generated files not found.")
except subprocess.CalledProcessError as e:
print(f"Error during generation: {e}")
print("STDOUT:", e.stdout)
print("STDERR:", e.stderr)
print("Make sure 'protoc' is available in your PATH or installed via grpcio-tools.")
except FileNotFoundError as e:
print(f"Error: Python or the generator script was not found. {e}")
# Clean up generated files
# os.remove("example.proto")
# if os.path.exists("example.pb.h"): os.remove("example.pb.h")
# if os.path.exists("example.pb.c"): os.remove("example.pb.c")
nanopb_generator.py --version
Debug
Known issues
breakingPython 2 support was officially removed in nanopb 0.4.x. The generator script now requires Python 3.fixEnsure you are running the `nanopb_generator.py` script with `python3` and that `protobuf` (python-protobuf) is installed for Python 3.
affects: 0.4.0 and later
gotchaThe `nanopb_generator.py` script internally calls the `protoc` (Protocol Buffers compiler) executable. This means `protoc` must be installed and discoverable in your system's PATH, or provided by the `grpcio-tools` Python package.fixInstall `grpcio-tools` via `pip install grpcio-tools` which bundles `protoc`, or ensure `protoc` is separately installed and accessible in your system's PATH.
affects: All versions
breakingSince nanopb 0.4.x, the `pb_common.c` file is always required by the C runtime library. Previously, it could be optionally excluded.fixAdd `pb_common.c` to your C project's build rules. Failure to do so will result in linker errors like `undefined reference to 'pb_common_init'`.
affects: 0.4.0 and later
breakingDefault generator options changed in nanopb 0.4.x. `--no-timestamp` and `--no-strip-path` are now enabled by default, which affects the `#include` directives in the generated C files.fixIf your C compiler cannot find generated header files, you may need to add `--strip-path` (or `--nanopb_out=--strip-path:outdir`) when running the generator to revert to the old behavior, or adjust your C compiler's include paths.
affects: 0.4.0 and later
gotchaThe compatibility between `nanopb`'s generator and `protobuf` / `grpcio-tools` versions can sometimes be fragile due to API changes in `python-protobuf`.fixIf encountering issues, try matching `protobuf` and `grpcio-tools` versions to those listed in `nanopb`'s `extra/requirements_lock.txt` on its GitHub repository, or using slightly older/newer versions known to be stable with your `nanopb` version.
affects: All versions (potential for specific combinations)
Upgrade
Version history
0.4.9.1latest on PyPI · released Dec 1, 2024
Audit
Dependencies
protobufrequiredRequired by `nanopb_generator.py` for parsing .proto files and generating C code.
grpcio-toolsrequiredProvides the `protoc` compiler, which is internally called by `nanopb_generator.py`.