{"id":8342,"library":"nanopb","title":"Nanopb Protocol Buffers Generator","description":"Nanopb is a small code-size Protocol Buffers implementation in ANSI C, primarily suitable for microcontrollers and other memory-restricted systems. The Python library component provides the `nanopb_generator.py` script, which compiles `.proto` definition files into C header (`.h`) and source (`.c`) files that can then be used with the Nanopb C runtime. The project is actively maintained, with versions typically released a few times a year, addressing bug fixes and minor improvements, such as the latest 0.4.9.1 release from December 2024.","status":"active","version":"0.4.9.1","language":"en","source_language":"en","source_url":"https://github.com/nanopb/nanopb/","tags":["protocol buffers","protobuf","embedded","generator","serialization","microcontroller"],"install":[{"cmd":"pip install nanopb","lang":"bash","label":"Install nanopb Python package"},{"cmd":"pip install --upgrade protobuf grpcio-tools","lang":"bash","label":"Install required dependencies for the generator"}],"dependencies":[{"reason":"Required by `nanopb_generator.py` for parsing .proto files and generating C code.","package":"protobuf"},{"reason":"Provides the `protoc` compiler, which is internally called by `nanopb_generator.py`.","package":"grpcio-tools"}],"imports":[{"note":"The primary interaction with the Python library is by executing the `nanopb_generator.py` script, not importing its modules into application code.","wrong":"import nanopb.generator","symbol":"nanopb_generator.py (script)","correct":"python -m nanopb.generator.nanopb_generator your_message.proto"}],"quickstart":{"code":"# 1. Define your Protocol Buffer message in a .proto file (e.g., example.proto):\n# message SimpleMessage {\n#   required int32 value = 1;\n# }\n\n# 2. Run the nanopb generator script:\nimport subprocess\nimport os\n\nproto_content = \"\"\"\nsyntax = \"proto2\";\n\nmessage SimpleMessage {\n  required int32 value = 1;\n}\n\"\"\"\n\nwith open(\"example.proto\", \"w\") as f:\n    f.write(proto_content)\n\n# Ensure protobuf and grpcio-tools are installed\ntry:\n    import google.protobuf\n    print(\"google.protobuf module found.\")\nexcept ImportError:\n    print(\"google.protobuf not found. Please install with: pip install protobuf grpcio-tools\")\n    exit(1)\n\n# Specify the path to the generator script\n# In an installed package, it's usually found via -m\ngenerator_path = \"nanopb.generator.nanopb_generator\"\n\nprint(f\"Generating C files from example.proto using {generator_path}...\")\ntry:\n    # Using python -m for installed package\n    result = subprocess.run(\n        [\"python\", \"-m\", generator_path, \"example.proto\"],\n        capture_output=True, text=True, check=True\n    )\n    print(\"STDOUT:\", result.stdout)\n    print(\"STDERR:\", result.stderr)\n    print(\"Successfully generated example.pb.h and example.pb.c\")\n\n    # Verify output files exist (optional)\n    if os.path.exists(\"example.pb.h\") and os.path.exists(\"example.pb.c\"):\n        print(\"Output files example.pb.h and example.pb.c found.\")\n    else:\n        print(\"Error: Generated files not found.\")\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error during generation: {e}\")\n    print(\"STDOUT:\", e.stdout)\n    print(\"STDERR:\", e.stderr)\n    print(\"Make sure 'protoc' is available in your PATH or installed via grpcio-tools.\")\nexcept FileNotFoundError as e:\n    print(f\"Error: Python or the generator script was not found. {e}\")\n\n# Clean up generated files\n# os.remove(\"example.proto\")\n# if os.path.exists(\"example.pb.h\"): os.remove(\"example.pb.h\")\n# if os.path.exists(\"example.pb.c\"): os.remove(\"example.pb.c\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you are running the `nanopb_generator.py` script with `python3` and that `protobuf` (python-protobuf) is installed for Python 3.","message":"Python 2 support was officially removed in nanopb 0.4.x. The generator script now requires Python 3.","severity":"breaking","affected_versions":"0.4.0 and later"},{"fix":"Install `grpcio-tools` via `pip install grpcio-tools` which bundles `protoc`, or ensure `protoc` is separately installed and accessible in your system's PATH.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `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'`.","message":"Since nanopb 0.4.x, the `pb_common.c` file is always required by the C runtime library. Previously, it could be optionally excluded.","severity":"breaking","affected_versions":"0.4.0 and later"},{"fix":"If 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.","message":"Default 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.","severity":"breaking","affected_versions":"0.4.0 and later"},{"fix":"If 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.","message":"The compatibility between `nanopb`'s generator and `protobuf` / `grpcio-tools` versions can sometimes be fragile due to API changes in `python-protobuf`.","severity":"gotcha","affected_versions":"All versions (potential for specific combinations)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use `python -m nanopb.generator.nanopb_generator your_message.proto` instead of trying to run it directly as a file path.","cause":"The generator script is not being called correctly. When installed via pip, it's typically a module within the Python path.","error":"python: can't open file 'nanopb/generator/nanopb_generator.py': [Errno 2] No such file or directory"},{"fix":"Install the `protobuf` and `grpcio-tools` packages: `pip install protobuf grpcio-tools`. Ensure this is done for the Python environment you are using.","cause":"The Python `protobuf` library (or `python-protobuf` on some systems) is not installed or not available in the active Python environment, which the Nanopb generator depends on.","error":"ImportError: No module named google.protobuf.text_format"},{"fix":"Install `grpcio-tools` via `pip install grpcio-tools` (which includes `protoc`), or manually install the Protocol Buffers compiler (`protoc`) and ensure its directory is in your system's PATH.","cause":"The `protoc` executable, required by `nanopb_generator.py` for parsing .proto files, is not found in the system's PATH.","error":"protoc: command not found"},{"fix":"Change any imports of `options.proto` in your `.proto` files to `import \"nanopb/nanopb.proto\";` (or `generator/proto/nanopb.proto` depending on context and generator options).","cause":"In nanopb 0.4.x, the transitional `options.proto` file was removed. If your `.proto` files imported it, they will fail to generate.","error":"Errors about missing file options.proto when running the generator"},{"fix":"Provide all `.proto` files as arguments to `nanopb_generator.py` simultaneously to ensure submessage definitions are found. Alternatively, use the `(nanopb).descriptorsize = DS_4` option, or manually set `max_size` and `max_count` options in `.options` files to correctly inform the generator.","cause":"This C compile-time error indicates that a message or field exceeds its allocated size, or the generator didn't correctly detect submessage sizes.","error":"FIELDINFO_DOES_NOT_FIT_widthX (static assertion error in generated C code)"}]}