CINXE.COM
Overview | Protocol Buffers Documentation
<!doctype html><html itemscope itemtype=http://schema.org/WebPage lang=en class=no-js><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1,shrink-to-fit=no"><meta name=robots content="index, follow"><link rel="shortcut icon" href=/favicons/favicon.ico><link rel=apple-touch-icon href=/favicons/apple-touch-icon-180x180.png sizes=180x180><link rel=icon type=image/png href=/favicons/favicon-16x16.png sizes=16x16><link rel=icon type=image/png href=/favicons/favicon-32x32.png sizes=32x32><link rel=icon type=image/png href=/favicons/android-36x36.png sizes=36x36><link rel=icon type=image/png href=/favicons/android-48x48.png sizes=48x48><link rel=icon type=image/png href=/favicons/android-72x72.png sizes=72x72><link rel=icon type=image/png href=/favicons/android-96x96.png sizes=96x96><link rel=icon type=image/png href=/favicons/android-144x144.png sizes=144x144><link rel=icon type=image/png href=/favicons/android-192x192.png sizes=192x192><title>Overview | Protocol Buffers Documentation</title> <meta name=description content="Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data."><meta property="og:title" content="Overview"><meta property="og:description" content="Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data."><meta property="og:type" content="article"><meta property="og:url" content="https://protobuf.dev/overview/"><meta property="article:section" content><meta itemprop=name content="Overview"><meta itemprop=description content="Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data."><meta itemprop=wordCount content="1686"><meta itemprop=keywords content><meta name=twitter:card content="summary"><meta name=twitter:title content="Overview"><meta name=twitter:description content="Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data."><link rel=preload href=/scss/main.min.27bc098c9a8f7a1246d474f5c8afcee53760c9c7f38125d343ff52e0bf493011.css as=style integrity="sha256-J7wJjJqPehJG1HT1yK/O5TdgycfzgSXTQ/9S4L9JMBE=" crossorigin=anonymous><link href=/scss/main.min.27bc098c9a8f7a1246d474f5c8afcee53760c9c7f38125d343ff52e0bf493011.css rel=stylesheet integrity="sha256-J7wJjJqPehJG1HT1yK/O5TdgycfzgSXTQ/9S4L9JMBE=" crossorigin=anonymous><script src=https://code.jquery.com/jquery-3.7.1.min.js integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g==" crossorigin=anonymous></script><script async src="https://www.googletagmanager.com/gtag/js?id=G-5L8P8GRN4Y"></script><script>var doNotTrack=!1,dnt;if(!1&&(dnt=navigator.doNotTrack||window.doNotTrack||navigator.msDoNotTrack,doNotTrack=dnt=="1"||dnt=="yes"),!doNotTrack){window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}gtag("js",new Date),gtag("config","G-5L8P8GRN4Y")}</script></head><body class=td-page><header><nav class="td-navbar js-navbar-scroll" data-bs-theme=dark><div class="container-fluid flex-column flex-md-row"><a class=navbar-brand href=/><span class="navbar-brand__logo navbar-logo"></span><span class=navbar-brand__name>Protocol Buffers Documentation</span></a><div class="td-navbar-nav-scroll ms-md-auto" id=main_navbar><ul class=navbar-nav></ul></div><div class="d-none d-lg-block"><div class=td-search><div class=td-search__icon></div><input type=search class="td-search__input form-control td-search-input" placeholder="Search this site…" aria-label="Search this site…" autocomplete=off></div></div></div></nav></header><div class="container-fluid td-outer"><div class=td-main><div class="row flex-xl-nowrap"><aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none"><div id=td-sidebar-menu class=td-sidebar__inner><div id=content-mobile><form class="td-sidebar__search d-flex align-items-center"><div class=td-search><div class=td-search__icon></div><input type=search class="td-search__input form-control td-search-input" placeholder="Search this site…" aria-label="Search this site…" autocomplete=off></div><button class="btn btn-link td-sidebar__toggle d-md-none p-0 ms-3 fas fa-bars" type=button data-bs-toggle=collapse data-bs-target=#td-section-nav aria-controls=td-section-nav aria-expanded=false aria-label="Toggle section navigation"></button></form></div><div id=content-desktop></div><nav class="td-sidebar-nav collapse td-sidebar-nav--search-disabled" id=td-section-nav><ul class="td-sidebar-nav__section pe-md-3 ul-0"><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child active-path" id=m--li><a href=/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section tree-root" id=m-><span>Protocol Buffers</span></a><ul class=ul-1><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child active-path" id=m-overview-li><a href=/overview/ class="align-left ps-0 active td-sidebar-link td-sidebar-link__page" id=m-overview><span class=td-sidebar-nav-active-item>Overview</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-installation-li><a href=/installation/ title="Protocol Buffer Compiler Installation" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-installation><span>Protoc Installation</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-news-li><a href=/news/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-news><span>News</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-programming-guides-li><a href=/programming-guides/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-programming-guides><span>Programming Guides</span></a><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guideseditions-li><a href=/programming-guides/editions/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guideseditions><span>Language Guide (editions)</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesproto2-li><a href=/programming-guides/proto2/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesproto2><span>Language Guide (proto 2)</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesproto3-li><a href=/programming-guides/proto3/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesproto3><span>Language Guide (proto 3)</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesproto-limits-li><a href=/programming-guides/proto-limits/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesproto-limits><span>Proto Limits</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesstyle-li><a href=/programming-guides/style/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesstyle><span>Style Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesenum-li><a href=/programming-guides/enum/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesenum><span>Enum Behavior</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesencoding-li><a href=/programming-guides/encoding/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesencoding><span>Encoding</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesjson-li><a href=/programming-guides/json/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesjson><span>ProtoJSON Format</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidestechniques-li><a href=/programming-guides/techniques/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidestechniques><span>Techniques</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesaddons-li><a href=/programming-guides/addons/ title="Third-Party Add-ons" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesaddons><span>Add-ons</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesextension_declarations-li><a href=/programming-guides/extension_declarations/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesextension_declarations><span>Extension Declarations</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesfield_presence-li><a href=/programming-guides/field_presence/ title="Application Note: Field Presence" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesfield_presence><span>Field Presence</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesserialization-not-canonical-li><a href=/programming-guides/serialization-not-canonical/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesserialization-not-canonical><span>Proto Serialization Is Not Canonical</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-programming-guidesdeserialize-debug-li><a href=/programming-guides/deserialize-debug/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-programming-guidesdeserialize-debug><span>Deserializing Debug Proto Representations</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-editions-li><a href=/editions/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-editions><span>Protobuf Editions</span></a><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-editionsoverview-li><a href=/editions/overview/ title="Protobuf Editions Overview" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-editionsoverview><span>Overview</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-editionsfeatures-li><a href=/editions/features/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-editionsfeatures><span>Feature Settings for Editions</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-editionsimplementation-li><a href=/editions/implementation/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-editionsimplementation><span>Implementing Editions Support</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-design-decisions-li><a href=/design-decisions/ title="Protobuf Team Design Decisions" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-design-decisions><span>Design Decisions</span></a><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-design-decisionsnullable-getters-setters-li><a href=/design-decisions/nullable-getters-setters/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-design-decisionsnullable-getters-setters><span>No Nullable Setters/Getters Support</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-best-practices-li><a href=/best-practices/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-best-practices><span>Proto Best Practices</span></a><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-best-practicesno-cargo-cults-li><a href=/best-practices/no-cargo-cults/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-best-practicesno-cargo-cults><span>Avoid Cargo Culting</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-best-practicesdos-donts-li><a href=/best-practices/dos-donts/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-best-practicesdos-donts><span>Proto Best Practices</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-best-practicesapi-li><a href=/best-practices/api/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-best-practicesapi><span>API Best Practices</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-best-practices1-1-1-li><a href=/best-practices/1-1-1/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-best-practices1-1-1><span>1-1-1 Best Practice</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-getting-started-li><a href=/getting-started/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-getting-started><span>Tutorials</span></a><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-getting-startedcpptutorial-li><a href=/getting-started/cpptutorial/ title="Protocol Buffer Basics: C++" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-getting-startedcpptutorial><span>C++</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-getting-startedcsharptutorial-li><a href=/getting-started/csharptutorial/ title="Protocol Buffer Basics: C#" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-getting-startedcsharptutorial><span>C#</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-getting-starteddarttutorial-li><a href=/getting-started/darttutorial/ title="Protocol Buffer Basics: Dart" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-getting-starteddarttutorial><span>Dart</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-getting-startedgotutorial-li><a href=/getting-started/gotutorial/ title="Protocol Buffer Basics: Go" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-getting-startedgotutorial><span>Go</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-getting-startedjavatutorial-li><a href=/getting-started/javatutorial/ title="Protocol Buffer Basics: Java" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-getting-startedjavatutorial><span>Java</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-getting-startedkotlintutorial-li><a href=/getting-started/kotlintutorial/ title="Protocol Buffer Basics: Kotlin" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-getting-startedkotlintutorial><span>Kotlin</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-getting-startedpythontutorial-li><a href=/getting-started/pythontutorial/ title="Protocol Buffer Basics: Python" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-getting-startedpythontutorial><span>Python</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-reference-li><a href=/reference/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-reference><span>Reference Guides</span></a><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencecpp-li><a href=/reference/cpp/ title="C++ Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencecpp><span>C++</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencecppcpp-generated-li><a href=/reference/cpp/cpp-generated/ title="C++ Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencecppcpp-generated><span>Generated Code Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencecppstring-view-li><a href=/reference/cpp/string-view/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencecppstring-view><span>String View APIs</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencecpparenas-li><a href=/reference/cpp/arenas/ title="C++ Arena Allocation Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencecpparenas><span>Arena Allocation Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencecppabseil-li><a href=/reference/cpp/abseil/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencecppabseil><span>Abseil Support</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencecppapi-docs-link-li><a href=/reference/cpp/api-docs/ target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencecppapi-docs-link><span>C++ API</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencecsharp-li><a href=/reference/csharp/ title="C# Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencecsharp><span>C#</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencecsharpcsharp-generated-li><a href=/reference/csharp/csharp-generated/ title="C# Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencecsharpcsharp-generated><span>Generated Code Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencecsharpapi-docs-link-li><a href=/reference/csharp/api-docs target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencecsharpapi-docs-link><span>C# API</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencedart-li><a href=/reference/dart/ title="Dart Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencedart><span>Dart</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencedartdart-generated-li><a href=/reference/dart/dart-generated/ title="Dart Generated Code" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencedartdart-generated><span>Generated Code</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencedartapi-docs-link-li><a href=https://pub.dartlang.org/documentation/protobuf target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencedartapi-docs-link><span>Dart API</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencego-li><a href=/reference/go/ title="Go Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencego><span>Go</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegogo-generated-li><a href=/reference/go/go-generated/ title="Go Generated Code Guide (Open)" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegogo-generated><span>Generated Code Guide (Open)</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegogo-generated-opaque-li><a href=/reference/go/go-generated-opaque/ title="Go Generated Code Guide (Opaque)" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegogo-generated-opaque><span>Generated Code Guide (Opaque)</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegofaq-li><a href=/reference/go/faq/ title="Go FAQ" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegofaq><span>FAQ</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegosize-li><a href=/reference/go/size/ title="Go Size Semantics" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegosize><span>Size Semantics</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegoapi-docs-link-li><a href=https://pkg.go.dev/google.golang.org/protobuf/proto target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegoapi-docs-link><span>Go API</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegoopaque-migration-li><a href=/reference/go/opaque-migration/ title="Go Opaque API Migration" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegoopaque-migration><span>Opaque API Migration</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegoopaque-migration-manual-li><a href=/reference/go/opaque-migration-manual/ title="Go Opaque API: Manual Migration" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegoopaque-migration-manual><span>Opaque API: Manual Migration</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencegoopaque-faq-li><a href=/reference/go/opaque-faq/ title="Go Opaque API FAQ" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencegoopaque-faq><span>Opaque API FAQ</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencejava-li><a href=/reference/java/ title="Java Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencejava><span>Java</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencejavajava-generated-li><a href=/reference/java/java-generated/ title="Java Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencejavajava-generated><span>Generated Code Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencejavajava-proto-names-li><a href=/reference/java/java-proto-names/ title="Java Proto Names" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencejavajava-proto-names><span>Generated Proto Names</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencejavaapi-docs-link-li><a href=/reference/java/api-docs/overview-summary.html target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencejavaapi-docs-link><span>Java API</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencekotlin-li><a href=/reference/kotlin/ title="Kotlin Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencekotlin><span>Kotlin</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencekotlinapi-docs-li><a href=/reference/kotlin/api-docs/ title="Kotlin Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencekotlinapi-docs><span>Kotlin</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencekotlinkotlin-generated-li><a href=/reference/kotlin/kotlin-generated/ title="Kotlin Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencekotlinkotlin-generated><span>Generated Code Guide</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referenceobjective-c-li><a href=/reference/objective-c/ title="Objective-C Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referenceobjective-c><span>Objective-C</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referenceobjective-cobjective-c-generated-li><a href=/reference/objective-c/objective-c-generated/ title="Objective-C Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referenceobjective-cobjective-c-generated><span>Generated Code Guide</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencephp-li><a href=/reference/php/ title="PHP Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencephp><span>PHP</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencephpphp-generated-li><a href=/reference/php/php-generated/ title="PHP Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencephpphp-generated><span>Generated Code Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencephpapi-docs-link-li><a href=/reference/php/api-docs/ target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencephpapi-docs-link><span>PHP API</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referencepython-li><a href=/reference/python/ title="Python Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referencepython><span>Python</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencepythonpython-generated-li><a href=/reference/python/python-generated/ title="Python Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencepythonpython-generated><span>Generated Code Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencepythonapi-docs-link-li><a href=https://googleapis.dev/python/protobuf/latest/ target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencepythonapi-docs-link><span>Python API</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referenceruby-li><a href=/reference/ruby/ title="Ruby Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referenceruby><span>Ruby</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referencerubyruby-generated-li><a href=/reference/ruby/ruby-generated/ title="Ruby Generated Code Guide" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referencerubyruby-generated><span>Generated Code Guide</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-referenceprotobuf-li><a href=/reference/protobuf/ title="Protocol Buffers Reference" class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-referenceprotobuf><span>Protocol Buffers</span></a><ul class="ul-3 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referenceprotobufedition-2023-spec-li><a href=/reference/protobuf/edition-2023-spec/ title="Protocol Buffers Edition 2023 Language Specification" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referenceprotobufedition-2023-spec><span>2023 Language Specification</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referenceprotobufproto2-spec-li><a href=/reference/protobuf/proto2-spec/ title="Protocol Buffers Version 2 Language Specification" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referenceprotobufproto2-spec><span>Version 2 Language Specification</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referenceprotobufproto3-spec-li><a href=/reference/protobuf/proto3-spec/ title="Protocol Buffers Version 3 Language Specification" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referenceprotobufproto3-spec><span>Version 3 Language Specification</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referenceprotobuftextformat-spec-li><a href=/reference/protobuf/textformat-spec/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referenceprotobuftextformat-spec><span>Text Format Language Specification</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referenceprotobufgoogleprotobuf-li><a href=/reference/protobuf/google.protobuf/ title="Protocol Buffers Well-Known Types" class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referenceprotobufgoogleprotobuf><span>Well-Known Types</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-referenceother-li><a href=/reference/other/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-referenceother><span>Other Languages</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section with-child" id=m-support-li><a href=/support/ class="align-left ps-0 td-sidebar-link td-sidebar-link__section" id=m-support><span>Support</span></a><ul class="ul-2 foldable"><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-supportversion-support-li><a href=/support/version-support/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-supportversion-support><span>Version Support</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-supportmigration-li><a href=/support/migration/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-supportmigration><span>Migration Guide</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-supportcross-version-runtime-guarantee-li><a href=/support/cross-version-runtime-guarantee/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-supportcross-version-runtime-guarantee><span>Cross-Version Runtime Guarantee</span></a></li></ul></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-downloads-li><a href=/downloads/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-downloads><span>Downloads</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-history-li><a href=/history/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-history><span>History</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-forum-link-li><a href=https://groups.google.com/g/protobuf target=_blank rel=noopener class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-forum-link><span>Forum</span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-navbar-li><a href=/navbar/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-navbar><span></span></a></li><li class="td-sidebar-nav__section-title td-sidebar-nav__section without-child" id=m-search-li><a href=/search/ class="align-left ps-0 td-sidebar-link td-sidebar-link__page" id=m-search><span>Search Results</span></a></li></ul></li></ul></nav></div></aside><aside class="d-none d-xl-block col-xl-2 td-sidebar-toc d-print-none"><div class="td-page-meta ml-2 pb-1 pt-2 mb-0"><a href=https://github.com/protocolbuffers/protocolbuffers.github.io/tree/main/content/overview.md class=td-page-meta--view target=_blank rel=noopener><i class="fa-solid fa-file-lines fa-fw"></i> View page source</a> <a href=https://github.com/protocolbuffers/protocolbuffers.github.io/edit/main/content/overview.md class=td-page-meta--edit target=_blank rel=noopener><i class="fa-solid fa-pen-to-square fa-fw"></i> Edit this page</a> <a href="https://github.com/protocolbuffers/protocolbuffers.github.io/new/main/content/overview.md?filename=change-me.md&value=---%0Atitle%3A+%22Long+Page+Title%22%0AlinkTitle%3A+%22Short+Nav+Title%22%0Aweight%3A+100%0Adescription%3A+%3E-%0A+++++Page+description+for+heading+and+indexes.%0A---%0A%0A%23%23+Heading%0A%0AEdit+this+template+to+create+your+new+page.%0A%0A%2A+Give+it+a+good+name%2C+ending+in+%60.md%60+-+e.g.+%60getting-started.md%60%0A%2A+Edit+the+%22front+matter%22+section+at+the+top+of+the+page+%28weight+controls+how+its+ordered+amongst+other+pages+in+the+same+directory%3B+lowest+number+first%29.%0A%2A+Add+a+good+commit+message+at+the+bottom+of+the+page+%28%3C80+characters%3B+use+the+extended+description+field+for+more+detail%29.%0A%2A+Create+a+new+branch+so+you+can+preview+your+new+file+and+request+a+review+via+Pull+Request.%0A" class=td-page-meta--child target=_blank rel=noopener><i class="fa-solid fa-pen-to-square fa-fw"></i> Create child page</a> <a href="https://github.com/protocolbuffers/protocolbuffers.github.io/issues/new?title=Overview" class=td-page-meta--issue target=_blank rel=noopener><i class="fa-solid fa-list-check fa-fw"></i> Create documentation issue</a> <a href=https://github.com/protocolbuffers/protobuf/issues/new class=td-page-meta--project-issue target=_blank rel=noopener><i class="fa-solid fa-list-check fa-fw"></i> Create project issue</a></div><div class=td-toc><nav id=TableOfContents><ul><li><a href=#solve>What Problems do Protocol Buffers Solve?</a></li><li><a href=#benefits>What are the Benefits of Using Protocol Buffers?</a><ul><li><a href=#cross-lang>Cross-language Compatibility</a></li><li><a href=#cross-proj>Cross-project Support</a></li><li><a href=#updating-defs>Updating Proto Definitions Without Updating Code</a></li><li><a href=#not-good-fit>When are Protocol Buffers not a Good Fit?</a></li></ul></li><li><a href=#who-uses>Who Uses Protocol Buffers?</a></li><li><a href=#work>How do Protocol Buffers Work?</a></li><li><a href=#syntax>Protocol Buffers Definition Syntax</a></li><li><a href=#data-types>Additional Data Type Support</a></li><li><a href=#history>History</a></li><li><a href=#philosophy>Protocol Buffers Open Source Philosophy</a></li><li><a href=#community>Developer Community</a></li><li><a href=#additional-resources>Additional Resources</a></li></ul></nav></div></aside><main class="col-12 col-md-9 col-xl-8 ps-md-5" role=main><nav aria-label=breadcrumb class="td-breadcrumbs td-breadcrumbs__single"><ol class=breadcrumb><li class="breadcrumb-item active" aria-current=page>Overview</li></ol></nav><div class=td-content><h1>Overview</h1><div class=lead>Protocol Buffers are a language-neutral, platform-neutral extensible mechanism for serializing structured data.</div><header class=article-meta></header><p>It’s like JSON, except it’s smaller and faster, and it generates native language bindings. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages.</p><p>Protocol buffers are a combination of the definition language (created in <code>.proto</code> files), the code that the proto compiler generates to interface with data, language-specific runtime libraries, the serialization format for data that is written to a file (or sent across a network connection), and the serialized data.</p><h2 id=solve>What Problems do Protocol Buffers Solve?</h2><p>Protocol buffers provide a serialization format for packets of typed, structured data that are up to a few megabytes in size. The format is suitable for both ephemeral network traffic and long-term data storage. Protocol buffers can be extended with new information without invalidating existing data or requiring code to be updated.</p><p>Protocol buffers are the most commonly-used data format at Google. They are used extensively in inter-server communications as well as for archival storage of data on disk. Protocol buffer <em>messages</em> and <em>services</em> are described by engineer-authored <code>.proto</code> files. The following shows an example <code>message</code>:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-proto data-lang=proto><span style=display:flex><span><span style=color:#000>edition</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#4e9a06>"2023"</span><span style=color:#000;font-weight:700>;</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span><span style=color:#204a87;font-weight:700>message</span> <span style=color:#000>Person</span> <span style=color:#000;font-weight:700>{</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span> <span style=color:#204a87;font-weight:700>string</span> <span style=color:#000>name</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#0000cf;font-weight:700>1</span><span style=color:#000;font-weight:700>;</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span> <span style=color:#204a87;font-weight:700>int32</span> <span style=color:#000>id</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#0000cf;font-weight:700>2</span><span style=color:#000;font-weight:700>;</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span> <span style=color:#204a87;font-weight:700>string</span> <span style=color:#000>email</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#0000cf;font-weight:700>3</span><span style=color:#000;font-weight:700>;</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span><span style=color:#000;font-weight:700>}</span><span style=color:#a40000> </span></span></span></code></pre></div><p>The proto compiler is invoked at build time on <code>.proto</code> files to generate code in various programming languages (covered in <a href=#cross-lang>Cross-language Compatibility</a> later in this topic) to manipulate the corresponding protocol buffer. Each generated class contains simple accessors for each field and methods to serialize and parse the whole structure to and from raw bytes. The following shows you an example that uses those generated methods:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>Person</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000>john</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#ce5c00;font-weight:700>=</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000>Person</span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>newBuilder</span><span style=color:#000;font-weight:700>()</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>setId</span><span style=color:#000;font-weight:700>(</span><span style=color:#000>1234</span><span style=color:#000;font-weight:700>)</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>setName</span><span style=color:#000;font-weight:700>(</span><span style=color:#4e9a06>"John Doe"</span><span style=color:#000;font-weight:700>)</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>setEmail</span><span style=color:#000;font-weight:700>(</span><span style=color:#4e9a06>"jdoe@example.com"</span><span style=color:#000;font-weight:700>)</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>build</span><span style=color:#000;font-weight:700>();</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline></span><span style=color:#000>output</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#ce5c00;font-weight:700>=</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#204a87;font-weight:700>new</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000>FileOutputStream</span><span style=color:#000;font-weight:700>(</span><span style=color:#000>args</span><span style=color:#ce5c00;font-weight:700>[</span><span style=color:#000>0</span><span style=color:#ce5c00;font-weight:700>]</span><span style=color:#000;font-weight:700>);</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline></span><span style=color:#000>john</span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>writeTo</span><span style=color:#000;font-weight:700>(</span><span style=color:#000>output</span><span style=color:#000;font-weight:700>);</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span></code></pre></div><p>Because protocol buffers are used extensively across all manner of services at Google and data within them may persist for some time, maintaining backwards compatibility is crucial. Protocol buffers allow for the seamless support of changes, including the addition of new fields and the deletion of existing fields, to any protocol buffer without breaking existing services. For more on this topic, see <a href=#updating-defs>Updating Proto Definitions Without Updating Code</a>, later in this topic.</p><h2 id=benefits>What are the Benefits of Using Protocol Buffers?</h2><p>Protocol buffers are ideal for any situation in which you need to serialize structured, record-like, typed data in a language-neutral, platform-neutral, extensible manner. They are most often used for defining communications protocols (together with gRPC) and for data storage.</p><p>Some of the advantages of using protocol buffers include:</p><ul><li>Compact data storage</li><li>Fast parsing</li><li>Availability in many programming languages</li><li>Optimized functionality through automatically-generated classes</li></ul><h3 id=cross-lang>Cross-language Compatibility</h3><p>The same messages can be read by code written in any supported programming language. You can have a Java program on one platform capture data from one software system, serialize it based on a <code>.proto</code> definition, and then extract specific values from that serialized data in a separate Python application running on another platform.</p><p>The following languages are supported directly in the protocol buffers compiler, protoc:</p><ul><li><a href=/reference/cpp/cpp-generated#invocation>C++</a></li><li><a href=/reference/csharp/csharp-generated#invocation>C#</a></li><li><a href=/reference/java/java-generated#invocation>Java</a></li><li><a href=/reference/kotlin/kotlin-generated#invocation>Kotlin</a></li><li><a href=/reference/objective-c/objective-c-generated#invocation>Objective-C</a></li><li><a href=/reference/php/php-generated#invocation>PHP</a></li><li><a href=/reference/python/python-generated#invocation>Python</a></li><li><a href=/reference/ruby/ruby-generated#invocation>Ruby</a></li></ul><p>The following languages are supported by Google, but the projects’ source code resides in GitHub repositories. The protoc compiler uses plugins for these languages:</p><ul><li><a href=https://github.com/google/protobuf.dart>Dart</a></li><li><a href=https://github.com/protocolbuffers/protobuf-go>Go</a></li></ul><p>Additional languages are not directly supported by Google, but rather by other GitHub projects. These languages are covered in <a href=https://github.com/protocolbuffers/protobuf/blob/master/docs/third_party.md>Third-Party Add-ons for Protocol Buffers</a>.</p><h3 id=cross-proj>Cross-project Support</h3><p>You can use protocol buffers across projects by defining <code>message</code> types in <code>.proto</code> files that reside outside of a specific project’s code base. If you’re defining <code>message</code> types or enums that you anticipate will be widely used outside of your immediate team, you can put them in their own file with no dependencies.</p><p>A couple of examples of proto definitions widely-used within Google are <a href=https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/timestamp.proto><code>timestamp.proto</code></a> and <a href=https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto><code>status.proto</code></a>.</p><h3 id=updating-defs>Updating Proto Definitions Without Updating Code</h3><p>It’s standard for software products to be backward compatible, but it is less common for them to be forward compatible. As long as you follow some <a href=/programming-guides/proto3#updating>simple practices</a> when updating <code>.proto</code> definitions, old code will read new messages without issues, ignoring any newly added fields. To the old code, fields that were deleted will have their default value, and deleted repeated fields will be empty. For information on what “repeated” fields are, see <a href=#syntax>Protocol Buffers Definition Syntax</a> later in this topic.</p><p>New code will also transparently read old messages. New fields will not be present in old messages; in these cases protocol buffers provide a reasonable default value.</p><h3 id=not-good-fit>When are Protocol Buffers not a Good Fit?</h3><p>Protocol buffers do not fit all data. In particular:</p><ul><li>Protocol buffers tend to assume that entire messages can be loaded into memory at once and are not larger than an object graph. For data that exceeds a few megabytes, consider a different solution; when working with larger data, you may effectively end up with several copies of the data due to serialized copies, which can cause surprising spikes in memory usage.</li><li>When protocol buffers are serialized, the same data can have many different binary serializations. You cannot compare two messages for equality without fully parsing them.</li><li>Messages are not compressed. While messages can be zipped or gzipped like any other file, special-purpose compression algorithms like the ones used by JPEG and PNG will produce much smaller files for data of the appropriate type.</li><li>Protocol buffer messages are less than maximally efficient in both size and speed for many scientific and engineering uses that involve large, multi-dimensional arrays of floating point numbers. For these applications, <a href=https://en.wikipedia.org/wiki/FITS>FITS</a> and similar formats have less overhead.</li><li>Protocol buffers are not well supported in non-object-oriented languages popular in scientific computing, such as Fortran and IDL.</li><li>Protocol buffer messages don’t inherently self-describe their data, but they have a fully reflective schema that you can use to implement self-description. That is, you cannot fully interpret one without access to its corresponding <code>.proto</code> file.</li><li>Protocol buffers are not a formal standard of any organization. This makes them unsuitable for use in environments with legal or other requirements to build on top of standards.</li></ul><h2 id=who-uses>Who Uses Protocol Buffers?</h2><p>Many projects use protocol buffers, including the following:</p><ul><li><a href=https://grpc.io>gRPC</a></li><li><a href=https://cloud.google.com>Google Cloud</a></li><li><a href=https://www.envoyproxy.io>Envoy Proxy</a></li></ul><h2 id=work>How do Protocol Buffers Work?</h2><p>The following diagram shows how you use protocol buffers to work with your data.</p><p><img src=/images/protocol-buffers-concepts.png alt="Compilation workflow showing the creation of a proto file, generated code, and compiled classes"><br><strong>Figure 1. Protocol buffers workflow</strong></p><p>The code generated by protocol buffers provides utility methods to retrieve data from files and streams, extract individual values from the data, check if data exists, serialize data back to a file or stream, and other useful functions.</p><p>The following code samples show you an example of this flow in Java. As shown earlier, this is a <code>.proto</code> definition:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-proto data-lang=proto><span style=display:flex><span><span style=color:#204a87;font-weight:700>message</span> <span style=color:#000>Person</span> <span style=color:#000;font-weight:700>{</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span> <span style=color:#204a87;font-weight:700>string</span> <span style=color:#000>name</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#0000cf;font-weight:700>1</span><span style=color:#000;font-weight:700>;</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span> <span style=color:#204a87;font-weight:700>int32</span> <span style=color:#000>id</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#0000cf;font-weight:700>2</span><span style=color:#000;font-weight:700>;</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span> <span style=color:#204a87;font-weight:700>string</span> <span style=color:#000>email</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#0000cf;font-weight:700>3</span><span style=color:#000;font-weight:700>;</span><span style=color:#a40000> </span></span></span><span style=display:flex><span><span style=color:#a40000></span><span style=color:#000;font-weight:700>}</span><span style=color:#a40000> </span></span></span></code></pre></div><p>Compiling this <code>.proto</code> file creates a <code>Builder</code> class that you can use to create new instances, as in the following Java code:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=display:flex><span><span style=color:#000>Person</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000>john</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#ce5c00;font-weight:700>=</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000>Person</span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>newBuilder</span><span style=color:#000;font-weight:700>()</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>setId</span><span style=color:#000;font-weight:700>(</span><span style=color:#000>1234</span><span style=color:#000;font-weight:700>)</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>setName</span><span style=color:#000;font-weight:700>(</span><span style=color:#4e9a06>"John Doe"</span><span style=color:#000;font-weight:700>)</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>setEmail</span><span style=color:#000;font-weight:700>(</span><span style=color:#4e9a06>"jdoe@example.com"</span><span style=color:#000;font-weight:700>)</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>build</span><span style=color:#000;font-weight:700>();</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline></span><span style=color:#000>output</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#ce5c00;font-weight:700>=</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#204a87;font-weight:700>new</span><span style=color:#f8f8f8;text-decoration:underline> </span><span style=color:#000>FileOutputStream</span><span style=color:#000;font-weight:700>(</span><span style=color:#000>args</span><span style=color:#ce5c00;font-weight:700>[</span><span style=color:#000>0</span><span style=color:#ce5c00;font-weight:700>]</span><span style=color:#000;font-weight:700>);</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span><span style=display:flex><span><span style=color:#f8f8f8;text-decoration:underline></span><span style=color:#000>john</span><span style=color:#000;font-weight:700>.</span><span style=color:#c4a000>writeTo</span><span style=color:#000;font-weight:700>(</span><span style=color:#000>output</span><span style=color:#000;font-weight:700>);</span><span style=color:#f8f8f8;text-decoration:underline> </span></span></span></code></pre></div><p>You can then deserialize data using the methods protocol buffers creates in other languages, like C++:</p><div class=highlight><pre tabindex=0 style=background-color:#f8f8f8;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#000>Person</span> <span style=color:#000>john</span><span style=color:#000;font-weight:700>;</span> </span></span><span style=display:flex><span><span style=color:#000>fstream</span> <span style=color:#000>input</span><span style=color:#000;font-weight:700>(</span><span style=color:#000>argv</span><span style=color:#000;font-weight:700>[</span><span style=color:#0000cf;font-weight:700>1</span><span style=color:#000;font-weight:700>],</span> <span style=color:#000>ios</span><span style=color:#ce5c00;font-weight:700>::</span><span style=color:#000>in</span> <span style=color:#ce5c00;font-weight:700>|</span> <span style=color:#000>ios</span><span style=color:#ce5c00;font-weight:700>::</span><span style=color:#000>binary</span><span style=color:#000;font-weight:700>);</span> </span></span><span style=display:flex><span><span style=color:#000>john</span><span style=color:#000;font-weight:700>.</span><span style=color:#000>ParseFromIstream</span><span style=color:#000;font-weight:700>(</span><span style=color:#ce5c00;font-weight:700>&</span><span style=color:#000>input</span><span style=color:#000;font-weight:700>);</span> </span></span><span style=display:flex><span><span style=color:#204a87;font-weight:700>int</span> <span style=color:#000>id</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#000>john</span><span style=color:#000;font-weight:700>.</span><span style=color:#000>id</span><span style=color:#000;font-weight:700>();</span> </span></span><span style=display:flex><span><span style=color:#000>std</span><span style=color:#ce5c00;font-weight:700>::</span><span style=color:#000>string</span> <span style=color:#000>name</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#000>john</span><span style=color:#000;font-weight:700>.</span><span style=color:#000>name</span><span style=color:#000;font-weight:700>();</span> </span></span><span style=display:flex><span><span style=color:#000>std</span><span style=color:#ce5c00;font-weight:700>::</span><span style=color:#000>string</span> <span style=color:#000>email</span> <span style=color:#ce5c00;font-weight:700>=</span> <span style=color:#000>john</span><span style=color:#000;font-weight:700>.</span><span style=color:#000>email</span><span style=color:#000;font-weight:700>();</span> </span></span></code></pre></div><h2 id=syntax>Protocol Buffers Definition Syntax</h2><p>When defining <code>.proto</code> files, you can specify cardinality (singular or repeated). In proto2 and proto3, you can also specify if the field is optional. In proto3, setting a field to optional <a href=/programming-guides/field_presence>changes it from implicit presence to explicit presence</a>.</p><p>After setting the cardinality of a field, you specify the data type. Protocol buffers support the usual primitive data types, such as integers, booleans, and floats. For the full list, see <a href=/programming-guides/proto3#scalar>Scalar Value Types</a>.</p><p>A field can also be of:</p><ul><li>A <code>message</code> type, so that you can nest parts of the definition, such as for repeating sets of data.</li><li>An <code>enum</code> type, so you can specify a set of values to choose from.</li><li>A <code>oneof</code> type, which you can use when a message has many optional fields and at most one field will be set at the same time.</li><li>A <code>map</code> type, to add key-value pairs to your definition.</li></ul><p>Messages can allow <strong>extensions</strong> to define fields outside of the message, itself. For example, the protobuf library’s internal message schema allows extensions for custom, usage-specific options.</p><p>For more information about the options available, see the language guide for <a href=/programming-guides/proto2>proto2</a>, <a href=/programming-guides/proto3>proto3</a>, or <a href=/programming-guides/editions>edition 2023</a>.</p><p>After setting cardinality and data type, you choose a name for the field. There are some things to keep in mind when setting field names:</p><ul><li>It can sometimes be difficult, or even impossible, to change field names after they’ve been used in production.</li><li>Field names cannot contain dashes. For more on field name syntax, see <a href=/programming-guides/style#message-field-names>Message and Field Names</a>.</li><li>Use pluralized names for repeated fields.</li></ul><p>After assigning a name to the field, you assign a field number. Field numbers cannot be repurposed or reused. If you delete a field, you should reserve its field number to prevent someone from accidentally reusing the number.</p><h2 id=data-types>Additional Data Type Support</h2><p>Protocol buffers support many scalar value types, including integers that use both variable-length encoding and fixed sizes. You can also create your own composite data types by defining messages that are, themselves, data types that you can assign to a field. In addition to the simple and composite value types, several <a href=/best-practices/dos-donts#common>common types</a> are published.</p><h2 id=history>History</h2><p>To read about the history of the protocol buffers project, see <a href=/history>History of Protocol Buffers</a>.</p><h2 id=philosophy>Protocol Buffers Open Source Philosophy</h2><p>Protocol buffers were open sourced in 2008 as a way to provide developers outside of Google with the same benefits that we derive from them internally. We support the open source community through regular updates to the language as we make those changes to support our internal requirements. While we accept select pull requests from external developers, we cannot always prioritize feature requests and bug fixes that don’t conform to Google’s specific needs.</p><h2 id=community>Developer Community</h2><p>To be alerted to upcoming changes in Protocol Buffers and to connect with protobuf developers and users, <a href=https://groups.google.com/g/protobuf>join the Google Group</a>.</p><h2 id=additional-resources>Additional Resources</h2><ul><li><a href=https://github.com/protocolbuffers/protobuf/>Protocol Buffers GitHub</a><ul><li><a href=https://protobuf.dev/getting-started/>Tutorials</a></li></ul></li></ul></div></main></div></div><footer class="bg-dark py-5 row d-print-none"><div class="container-fluid mx-sm-5"><div class=row><div class="col-6 col-sm-4 text-xs-center order-sm-2"><ul class="list-inline mb-0"><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title="Stack Overflow" aria-label="Stack Overflow"><a class=text-white target=_blank rel=noopener href=https://stackoverflow.com/questions/tagged/protocol-buffers aria-label="Stack Overflow"><i class="fab fa-stack-overflow"></i></a></li></ul><script type=text/javascript id=cookiebanner src=https://cdn.jsdelivr.net/gh/dobarkod/cookie-banner@1.2.2/dist/cookiebanner.min.js data-height=50px data-message="Protobuf.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic." data-bg=#ffb data-fg=#000 data-position=bottom data-padding="10px 16px" data-close-text="OK, got it" data-font-size=18px data-moreinfo=https://policies.google.com/technologies/cookies></script></div><div class="col-6 col-sm-4 text-right text-xs-center order-sm-3"><ul class="list-inline mb-0"><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title=GitHub aria-label=GitHub><a class=text-white target=_blank rel=noopener href=https://github.com/protocolbuffers/protobuf aria-label=GitHub><i class="fab fa-github"></i></a></li><li class="list-inline-item mx-2 h3" data-toggle=tooltip data-placement=top title="Developer mailing list" aria-label="Developer mailing list"><a class=text-white target=_blank rel=noopener href=https://groups.google.com/g/protobuf aria-label="Developer mailing list"><i class="fa fa-envelope"></i></a></li></ul><script type=text/javascript id=cookiebanner src=https://cdn.jsdelivr.net/gh/dobarkod/cookie-banner@1.2.2/dist/cookiebanner.min.js data-height=50px data-message="Protobuf.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic." data-bg=#ffb data-fg=#000 data-position=bottom data-padding="10px 16px" data-close-text="OK, got it" data-font-size=18px data-moreinfo=https://policies.google.com/technologies/cookies></script></div><div class="col-12 col-sm-4 text-center py-2 order-sm-2"><small class=text-white>© 2025 Google LLC All Rights Reserved</small> <small class=ml-1><a href=https://policies.google.com/privacy target=_blank rel=noopener>Privacy Policy</a></small> <span class=text-white>Hosted by GitHub Pages.</span> <a href=https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement target=_blank>GitHub Privacy Statement</a></div></div></div></footer></div><script src=/js/main.min.c91cdfdcc1576ecc360abc6f1c3ca0485d047f65ac6d3203ec57ed29e0af808b.js integrity="sha256-yRzf3MFXbsw2CrxvHDygSF0Ef2WsbTID7FftKeCvgIs=" crossorigin=anonymous></script><script defer src=/js/click-to-copy.min.73478a7d4807698aed7e355eb23f9890ca18fea3158604c8471746d046702bad.js integrity="sha256-c0eKfUgHaYrtfjVesj+YkMoY/qMVhgTIRxdG0EZwK60=" crossorigin=anonymous></script><script src=/js/tabpane-persist.js></script></body></html>