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
ElixirMITCreated 2017-02-16
Download: v2.1.0v2.1.0 ↓2.1.02026-09-19
+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 op

Latest release

v2.1.0 v2.1.0 2026-09-19
Changed

- 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

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON