Skip to main content
Protocol Buffers allows you to define custom options by extending descriptor messages such as google.protobuf.FieldOptions or google.protobuf.MessageOptions. To avoid collisions between independent projects that define custom options, protobuf maintains a global extension registry.

​
What is the extension registry?

The extension registry is a public, authoritative list of extension number assignments for descriptor.proto options. Each entry records the project name, its website, and the extension number (or range) assigned to it. If you publish a project that uses custom options and your .proto files may be used alongside other third-party .proto files, you should register your extension number to prevent collisions.
The registry only covers extensions to the descriptor options messages (e.g., FileOptions, MessageOptions, FieldOptions, EnumOptions, ServiceOptions, MethodOptions). It does not cover field extensions in your own custom messages.

​
Registered extension numbers

The following table shows the first 20 registered entries from the global registry:
#ProjectExtension number(s)
1C# port of protocol buffers1000
2Perl/XS port of protocol buffers1001
3Objective-C port of protocol buffers1002
4Google Wave Federation Protocol (FedOne)1003
5PHP code generator plugin1004
6GWT code generator plugin1005
7Unix Domain RPC code generator plugin1006
8Objective-C generator plugin (Plausible Labs)1007
9TBD (code42.com)1008
10Goby Underwater Autonomy Project1009
11Nanopb1010
12Bluefin AUV Communication Extensions1011
13Dynamic Compact Control Language (DCCL)1012
14ScaleOut StateServer Native C++ API1013
15FoundationDB SQL Layer1014
16Fender1015
17Vortex1016
18tresorit1017
19CRIU (Checkpoint Restore In Userspace)1018
20protobuf-c1019
For the full list of all registered extensions, see docs/options.md in the protobuf repository.

​
How to define a custom option

Custom options are defined by extending the relevant descriptor options message: 
syntax = "proto3";

import "google/protobuf/descriptor.proto";

// Extend FieldOptions with your registered extension number.
extend google.protobuf.FieldOptions {
  string my_custom_option = 51234;  // Use your registered number
}

message MyMessage {
  string name = 1 [(my_custom_option) = "some value"];
}
You can extend any of the following descriptor messages:
Options messageScope
google.protobuf.FileOptionsApplied to a .proto file
google.protobuf.MessageOptionsApplied to a message type
google.protobuf.FieldOptionsApplied to a message field
google.protobuf.OneofOptionsApplied to a oneof group
google.protobuf.EnumOptionsApplied to an enum type
google.protobuf.EnumValueOptionsApplied to an enum value
google.protobuf.ServiceOptionsApplied to a service
google.protobuf.MethodOptionsApplied to an RPC method

​
Extension number ranges

RangePurpose
1 – 999Reserved for use by the Protocol Buffers implementation itself. Do not use.
1000 – 536,870,911Available for custom options; register your number in the global registry.
19000 – 19999Reserved for the Protocol Buffers implementation. Do not use.
Always register your extension numbers before publishing .proto files that use custom options. Using an unregistered number is fine for private use, but risks collision if your files are used alongside other third-party protos.

​
How to request an extension number

1

Choose an extension number

Pick any unregistered number in the range 1000–536,870,911. Check docs/options.md to confirm it is available.
2

Submit a pull request or issue

Register your number by doing one of the following:
  • Open a pull request that adds an entry to docs/options.md with your project name, website, and the extension number.
  • Open an issue with your project name and website, and the protobuf maintainers will add an entry for you.
3

Update your extension definition

Once your number is registered, use it in your .proto file’s extension definition.
If your project needs multiple extension numbers, you can request a contiguous range (e.g., 1500 to 1510). Describe your use case in the pull request or issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us