ahamez /protox
A reasonably fast, easy to use and 100% conformant Elixir library for Google Protocol Buffers (aka protobuf)
★ 299⑂ 22👁 3⑃ 288● 33▤ 55
+0
Daily
299
stars
22
forks
3
watchers
288
prs
33
issues
55
releases
README
Protox
Protox is an Elixir library for working with Google's Protocol Buffers (proto2 and proto3): encode/decode to/from binary, generate code, or compile schemas at build time.
Protox emphasizes reliability: it uses property testing, mutation testing, maintains near 100% coverage, and passes Google’s conformance suite.
[!NOTE]
Using v1? See the v2 migration guide in v1_to_v2_migration.md.
Example
Given the following protobuf definition:
proto
message Msg{
int32 a = 1;
map b = 2;
}
Protox will create a regular Elixir Msg struct:
elixir
iex msg = %Msg{a: 42, b: %{1 = "a map entry"}}
iex {:ok, iodata, iodata_size} = Msg.encode(msg)
iex binary = read binary from a socket, a file, etc.
iex {:ok, msg} = Msg.decode(binary)
Usage
You can use Protox in two ways:
1. pass the protobuf schema (as an inlined schema or as a list of files) to the Protox macro;
2. generate Elixir source code files with the mix task protox.generate.
Prerequisites
- Elixir = 1.15 and OTP = 26
- protoc = 3.0 _This dependency is only required at compile-time_. It must be available in $PATH.
Installation
Add :protox to your list of dependencies in mix.exs:
elixir
def deps do
[{:protox, "~ 2.0"}]
end
Usage with an inlined schema
The following example generates two modules, Baz and Foo:
elixir
defmodule MyModule do
use Protox, schema: """
syntax = "proto3";
message Baz {
}
message Foo {
int32 a = 1;
map b = 2;
}
"""
end
[!NOTE]
The module in which the Protox macro is called is ignored and does not appear in the names of the generated modules. To include the enclosing module’s name, use the namespace option, see here.
Usage with files
Use the :files option to pass a list of files:
elixir
defmodule MyModule do
use Protox, files: [
"./defs/foo.proto",
"./defs/bar.proto",
"./defs/baz/fiz.proto"
]
end
Encode
Here's how to encode a message to binary protobuf:
elixir
msg = %Foo{a: 3, b: %{1 = %Baz{}}}
{:ok, iodata, iodata_size} = Protox.encode(msg)
or using the bang version
{iodata, iodata_size} = Protox.encode!(msg)
You can also call encode/1 and encode!/1 directly on the generated structures:
elixir
{:ok, iodata, iodata_size} = Foo.encode(msg)
{iodata, iodata_size} = Foo.encode!(msg)
[!TIP]
encode/1 and encode!/1 return iodata for efficiency. Use it directly with file/socket writes, or convert with IO.iodata_to_binary/1 when you need a binary.
Decode
Here's how to decode a message from binary protobuf:
elixir
{:ok, msg} = Protox.decode(, Foo)
or using the bang version
msg = Protox.decode!(, Foo)
You can also call decode/1 and decode!/1 directly on the generated structures:
elixir
{:ok, msg} = Foo.decode()
msg = Foo.decode!()
Packages
Protox honors the package directive:
proto
package abc.def;
message Baz {}
The example above is translated to Abc.Def.Baz (package abc.def is camelized to Abc.Def).
Namespaces
You can prepend a namespace with a prefix using the :namespace opLatest release
v2.1.0 v2.1.0 2026-09-19Changed - Performance: encoding uses ~40% less memory, ~9% less CPU and ~37% fewer reductions; decoding uses ~30% less memory, ~30% less CPU and -60% fewer reductions - ⚠️ The generator version is now 2: files generated with a previous protox version must be regenerated (compilation fails with an explicit message otherwise) - Invalid field values are now attributed to their field (Protox.EncodingError) for more error classes (e.g. invalid bool values, structs of the wrong type); invalid scalar oneof values keep raising their raw error, whose type may differ (e.g. ArithmeticError instead o