Migration Guide

A list of the breaking changes made to versions of the libraries, and how to update your code to accommodate the changes.

Changes in v30.0

The following is a list of the breaking changes made to versions of the libraries, and how to update your code to accommodate the changes.

This covers breaking changes announced in News Announcements for v30.x and Release Notes for v30.0.

Replaced CMake Submodules with Fetched Deps

Previously, our default CMake behavior was to use Git submodules to grab pinned dependencies. Specifying -Dprotobuf_ABSL_PROVIDER=package would flip our CMake configs to look for local installations of Abseil (with similar options for jsoncpp and gtest). These options no longer exist, and the default behavior is to first look for installations of all our dependencies, falling back to fetching pinned versions from GitHub if needed.

To prevent any fallback fetching (similar to the old package behavior), you can call CMake with:

cmake . -Dprotobuf_LOCAL_DEPENDENCIES_ONLY=ON

To always fetch dependencies from a fixed version (similar to the old default behavior), you can call CMake with:

cmake . -Dprotobuf_FORCE_FETCH_DEPENDENCIES=ON

string_view return type

Return types are now absl::string_view for the following descriptor APIs, which opens up memory savings:

MessageLite::GetTypeName
UnknownField::length_delimited
Descriptor API name functions, such as FieldDescriptor::full_name

We expect future breaking releases to continue migrating additional APIs to absl::string_view.

In most cases, you should try to update types to use absl::string_view where safe, or explicitly copy to the original type where needed. You may need to update callers as well if this is returned in a function.

If the string returned by the affected API methods is being used as:

Type Migration

Type	Migration
`std::string`	Explicitly convert to `std::string` to preserve the existing behavior. Or, switch to the more performant `absl::string_view`
`const std::string&`	Migrate to `absl::string_view` If infeasible (such as due to large number of dependencies), copying to a `std::string` might be easier.
`const std::string` `const char`	If nullable, migrate to `std::optional<absl::string_view>`. Otherwise, migrate to `absl::string_view`. Be careful when calling `data()` since `absl::string_view` isn't guaranteed to be null-terminated.

std::string

Explicitly convert to std::string to preserve the existing behavior.

Or, switch to the more performant absl::string_view

const std::string&

Migrate to absl::string_view

If infeasible (such as due to large number of dependencies), copying to a std::string might be easier.

const std::string*

const char*

If nullable, migrate to std::optional<absl::string_view>.

Otherwise, migrate to absl::string_view.

Be careful when calling data() since absl::string_view isn't guaranteed to be null-terminated.

For common containers and other APIs, you may be able to migrate to variants compatible with absl::string_view. Below are some common examples.

Category Pre-Migration Migration

Category	Pre-Migration	Migration
Insertion into `std::vector<std::string>`	`push_back()` `push_front()` `push()`	`emplace_back()` `emplace_front()` `emplace()`
Insertion for map or sets	`set.insert(key)` `map.insert({key, value})` `map.insert({key, {value_params...}})`	`set.emplace(key)` `map.emplace(key, value)` `map.try_emplace(key, value_params...)`
Lookup for map or sets	`find()` `count()` `contains()`	Migrate to Abseil containers. Or, define a transparent comparator. `std::set<std::string, std::less<>> std::map<std::string, T, std::less<>>` See https://abseil.io/tips/144
String Concatenation	`operator+` `operator+=`	`absl::StrCat()` `absl::StrAppend()` These are recommended for performance reasons anyways. See https://abseil.io/tips/3.

Insertion into std::vector<std::string>

push_back()

push_front()

push()

emplace_back()

emplace_front()

emplace()

Insertion for map or sets

set.insert(key)

map.insert({key, value})

map.insert({key, {value_params...}})

set.emplace(key)

map.emplace(key, value)

map.try_emplace(key, value_params...)

Lookup for map or sets

find()

count()

contains()

Migrate to Abseil containers.

Or, define a transparent comparator.

std::set<std::string, std::less<>> std::map<std::string, T, std::less<>>

See https://abseil.io/tips/144

String Concatenation

operator+

operator+=

absl::StrCat()

absl::StrAppend()

These are recommended for performance reasons anyways. See https://abseil.io/tips/3.

See also https://abseil.io/tips/1 for general tips around using absl::string_view.

Poison MSVC + Bazel

Bazel users on Windows should switch to using clang-cl by adding the following to their project, like in this example.

.bazelrc

common --enable_platform_specific_config build:windows
--extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl
--extra_execution_platforms=//:x64_windows-clang-cl

MODULE.bazel

bazel_dep(name = "platforms", version = "0.0.10")
bazel_dep(name = "rules_cc", version = "0.0.17")

# For clang-cl configuration
cc_configure = use_extension("@rules_cc//cc:extensions.bzl", "cc_configure_extension")
use_repo(cc_configure, "local_config_cc")

WORKSPACE

load("//:protobuf_deps.bzl", "PROTOBUF_MAVEN_ARTIFACTS", "protobuf_deps")

protobuf_deps()

load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains")

rules_cc_dependencies()

rules_cc_toolchains()

BUILD

For users that need compatibility with Bazel 8 only.

platform(
    name = "x64_windows-clang-cl",
    constraint_values = [
        "@platforms//cpu:x86_64",
        "@platforms//os:windows",
        "@bazel_tools//tools/cpp:clang-cl",
    ],
)

For users that need compatibility with Bazel 7 and 8.

platform(
    name = "x64_windows-clang-cl",
    constraint_values = [
        "@platforms//cpu:x86_64",
        "@platforms//os:windows",
        # See https://github.com/bazelbuild/rules_cc/issues/330.
        "@rules_cc//cc/private/toolchain:clang-cl",
    ],
)

Users can also temporarily silence the error by setting the opt-out flag --define=protobuf_allow_msvc=true until the next breaking release.

Alternatively, users that wish to continue using MSVC may switch to using CMake. This can be done with Visual Studio, or by supplying the CMake command-line an MSVC generator. For example:

cmake -G "Visual Studio 17 2022" -A Win64 .

ctype Removed from FieldDescriptor Options

We stopped exposing the ctype from FieldDescriptor options. You can use the FieldDescriptor::cpp_string_type() API, added in the v28 release, in its place.

Modified Debug APIs to Redact Sensitive Fields

The Protobuf C++ debug APIs (including Protobuf AbslStringify, proto2::ShortFormat, proto2::Utf8Format, Message::DebugString, Message::ShortDebugString, Message::Utf8DebugString) changed to redact sensitive fields annotated by debug_redact; the outputs of these APIs contain a per-process randomized prefix, and are no longer parseable by Protobuf TextFormat Parsers. Users should adopt the new redacted debug format for most cases requiring a human-readable output (such as logging), or consider switching to binary format for serialization and deserialization. Users who need the old deserializable format can use TextFormat.printer().printToString(proto), but this does not redact sensitive fields and so should be used with caution.

Read more about this in the news article released December 4, 2024.

Removed Deprecated APIs

We removed the following public runtime APIs, which have been marked deprecated (such as ABSL_DEPRECATED) for at least one minor or major release and that are obsolete or replaced.

API: Arena::CreateMessage

Replacement: Arena::Create

API: Arena::GetArena

Replacement: value->GetArena()

API: RepeatedPtrField::ClearedCount

Replacement: Migrate to Arenas (migration guide).

API: JsonOptions

Replacement: JsonPrintOptions

Dropped C++14 Support

This release dropped C++ 14 as the minimum supported version and raised it to 17, as per the Foundational C++ Support matrix.

Users should upgrade to C++17.

Introduced ASAN Poisoning After Clearing Oneof Messages on Arena

This change added a hardening check that affects C++ protobufs using Arenas. Oneof messages allocated on the protobuf arena are now cleared in debug and poisoned in ASAN mode. After calling clear, future attempts to use the memory region will cause a crash in ASAN as a use-after-free error.

This implementation requires C++17.

Dropped our C++ CocoaPods release

We dropped our C++ CocoaPods release, which has been broken since v4.x.x. C++ users should use our GitHub release directly instead.

Changes in Python

Python bumped its major version from 5.29.x to 6.30.x.

Dropped Python 3.8 Support

The minimum supported Python version is 3.9. Users should upgrade.

Removed bazel/system_python.bzl Alias

We removed the legacy bazel/system_python.bzl alias.

Remove direct references to system_python.bzl in favor of using protobuf_deps.bzl instead. Use python/dist/system_python.bzl where it was moved in v5.27.0 if you need a direct reference.

Field Setter Validation Changes

Python’s and upb’s field setters now validate closed enums under edition 2023. Closed enum fields updated with invalid values generate errors.

Removed Deprecated py_proto_library Macro

The deprecated internal py_proto_library Bazel macro in protobuf.bzl was removed. It was replaced by the official py_proto_library which was moved to protobuf in bazel/py_proto_library in v29.x. This implementation was previously available in rules_python prior to v29.x.

Remove Deprecated APIs

We removed the following public runtime APIs, which had been marked deprecated for at least one minor or major release.

Reflection Methods

APIs: reflection.ParseMessage, reflection.MakeClass

Replacement: message_factory.GetMessageClass()

RPC Service Interfaces

APIs: service.RpcException, service.Service, service.RpcController, and service.RpcChannel

Replacement: Starting with version 2.3.0, RPC implementations should not try to build on these, but should instead provide code generator plugins which generate code specific to the particular RPC implementation.

MessageFactory and SymbolDatabase Methods

APIs: MessageFactory.GetPrototype, MessageFactory.CreatePrototype, MessageFactory.GetMessages, SymbolDatabase.GetPrototype, SymbolDatabase.CreatePrototype, and SymbolDatabase.GetMessages

Replacement: message_factory.GetMessageClass() and message_factory.GetMessageClassesForFiles().

GetDebugString

APIs: GetDebugString

Replacement:

No replacement. It’s only in Python C++ which is no longer released. It is not supported in pure Python or UPB.

Python setdefault Behavior Change for Map Fields

setdefault is similar to dict for ScalarMap, except that both key and value must be set. setdefault is rejected for MessageMaps.

Python Nested Message Class qualname Contains the Outer Message Name

Python nested message class __qualname__ now contains the outer message name. Previously, __qualname__ had the same result with __name__ for nested message, in that the outer message name was not included.

For example:

message Foo {
  message Bar {
    bool bool_field = 1;
  }
}
nested = test_pb2.Foo.Bar()
self.assertEqual('Bar', nested.__class__.__name__)
self.assertEqual('Foo.Bar', nested.__class__.__qualname__) # It was 'Bar' before

Changes in Objective-C

This is the first breaking release for Objective-C.

Objective-C bumped its major version from 3.x.x to 4.30.x.

Overhauled Unknown Field Handling APIs Deprecating Most of the Existing APIs

We deprecated GPBUnknownFieldSet and replaced it with GPBUnknownFields. The new type preserves the ordering of unknown fields from the original input or API calls, to ensure any semantic meaning to the ordering is maintained when a message is written back out.

As part of this, the GPBUnknownField type also has APIs changes, with almost all of the existing APIs deprecated and new ones added.

Deprecated property APIs:

varintList
fixed32List
fixed64List
lengthDelimitedList
groupList

Deprecated modification APIs:

addVarint:
addFixed32:
addFixed64:
addLengthDelimited:
addGroup:

Deprecated initializer initWithNumber:.

New property APIs:

type
varint
fixed32
fixed64
lengthDelimited
group

This type models a single field number in its value, rather than grouping all the values for a given field number. The APIs for creating new fields are the add* APIs on the GPBUnknownFields class.

We also deprecated -[GPBMessage unknownFields]. In its place, there are new APIs to extract and update the unknown fields of the message.

Removed Deprecated APIs

We removed the following public runtime APIs, which had been marked deprecated for at least one minor or major release.

GPBFileDescriptor

API: -[GPBFileDescriptor syntax]

Replacement: Obsolete.

Replacement: Obsolete - Use GPBTextFormatForMessage(), which includes any unknown fields.

GPBUnknownFieldSet

API: GPBUnknownFieldSet

Replacement: GPBUnknownFields

GPBMessage unknownFields

API: GPBMessage unknownFields property

Replacement: -[GPBUnknownFields initFromMessage:], -[GPBMessage mergeUnknownFields:extensionRegistry:error:], and -[GPBMessage clearUnknownFields]

Removed Deprecated Runtime APIs for Old Gencode

This release removed deprecated runtime methods that supported the Objective-C gencode from before the 3.22.x release. The library also issues a log message at runtime when old generated code is starting up.

API: +[GPBFileDescriptor allocDescriptorForClass:file:fields:fieldCount:storageSize:flags:]