Changes Announced on September 22, 2026
The following sections cover planned breaking changes in the v38 release, expected in 2027 Q1. These describe changes as we anticipate them being implemented, but due to the flexible nature of software some of these changes may not land or may vary from how they are described in this topic.
Changes in Bazel
Dropping Bazel 8 Support
This release will drop Bazel 8 as the minimum supported version and raise it to
Bazel 9, as per the Foundational C++ Support
Matrix.
As part of this change, support for legacy WORKSPACE builds will be removed,
and Bzlmod (MODULE.bazel) will be required.
Remove Deprecated APIs
Internal_py_proto_library
API: internal_py_proto_library()
Replacement: py_proto_library()
Remove Deprecated Flags
strict_proto_deps
Remove the --strict_proto_deps flag. Bazel build rules will always enforce
strict dependency checking for proto files. Users should ensure their
proto_library() targets follow proper layering.
cc_proto_library_header_suffixes
Remove --cc_proto_library_header_suffixes flag. Currently the
--cc_proto_library_header_suffixes flag allows users to set what header
suffixes our C++ codegen will generate. It defaults to [".pb.h"], but users
can set it to something else to make cc_proto_library() expect other suffixes.
cc_proto_library_source_suffixes
Remove the --cc_proto_library_source_suffixes. The default suffix will remain
.pb.cc and users can no longer set additional source suffixes to generate.
Flip strict_string_public_imports flag default
Flip --strict_string_public_imports flag default to be on. This enforces
strict checking for import public statements within .proto files against the
exports attribute of the proto_library target. Will fail to build if a .proto
file uses import public on a dependency that isn’t declared in exports.
Replace system_python with rules_python
Replace the @system_python repository and toolchain with standard
rules_python toolchains, removing @system_python entirely.
Downstream consumers that reference @system_python in their MODULE.bazel or
WORKSPACE files (such as references to @system_python//:python_headers,
@system_python//:pip.bzl, or @system_python//:interpreter) must migrate to
rules_python equivalents before upgrading, as Protobuf will no longer provide
@system_python.
Changes in C++
C++ will bump its major version from 7.37.x to 8.38.x.
Add [[nodiscard]]
Remove the PROTOBUF_FUTURE_ADD_NODISCARD macro. [[nodiscard]] was previously
introduced to several protobuf APIs to produce compile-time warnings for common
API misuses and avoid footguns. This change removes the temporary transition
flag macro, making the [[nodiscard]] annotations permanent.
Flip proto_h flag default
Flip proto_h default to True. By default, .proto.h files are emitted.
Remove Deprecated APIs
We are removing these APIs because they are not compatible with open enums.
Reflection::GetEnum()
API: Reflection::GetEnum()
Replacement: Reflection::GetEnumValue()
Reflection::GetRepeatedEnum()
API: Reflection::GetRepeatedEnum()
Replacement: Reflection::GetRepeatedEnumValue()
Generic Services Option
Disable code generation of cc_generic_services, as generic services have been
deprecated since they were introduced. You can revert to legacy behavior by
setting the protoc flag --allow_legacy_generic_services. This flag will be
removed in a future breaking release.
Changes in Java
Java will bump its major version from 4.37.x to 5.38.x. However, this is not an API breaking change and we will not be breaking generated code compatibility or poison pilling older generated code from 3.x.x in this release. The version bump is only to signal that certain notable behavioral changes are being released.
OneofDescriptor
Validate that oneof does not share the same name as any other descriptor. This
eliminates the risk of naming collisions, which can cause breakages.
Mark Internal Fields Transient
Mark several message implementation fields as transient so that they do not serialize in formats that respect the transient tag – particularly GSON. Do not use GSON on generated protobuf classes without one of the protobuf type adapters distributed with GSON.
UTF-8 Validation Feature
Respect UTF-8 validation feature for string extensions in all Editions.
Generic Services Option
Disable code generation of java_generic_services as generic services have been
deprecated since 2010. You can revert to legacy behavior by setting the protoc
flag --allow_legacy_generic_services. This flag will be removed in a future
breaking release.
Changes in Objective-C
Deprecating support for Objective-C. Objective-C will remain supported in our long term support release (37.x) until Q4 2027. Feedback may be left in the GitHub issue.
Changes in Python
Python will bump its major version from 7.37.x to 8.38.x.
Dropping Python 3.10 Support
This release will drop Python 3.10 as the minimum supported version and raise it to 3.11, as per the Foundational Python Support Matrix.
Immutable GetOptions()
The GetOptions() method on descriptor objects (such as Descriptor,
FieldDescriptor, and FileDescriptor) now returns an immutable options
message. Attempting to modify the returned options object raises
FrozenInstanceError.
Return NotImplemented for Unrecognized Types
When comparing equality against unrecognized types, the C++ and upb Python
protobuf implementations previously returned False directly. They now return
NotImplemented to follow standard Python comparison behavior and allow
reflected comparisons on the other operand.
RepeatedContainer.pop()
Calling pop() on a repeated field container with an index greater than or
equal to the container’s length in the upb implementation now raises
IndexError instead of clamping to the last element.
Decode \? to ?
Align Python’s textproto decoder with C++ and Java implementations by decoding
\? escape sequences to ?.
Enable NX and ASLR
Enable piping down NX and ASLR security feature flags to target repository
Parsing JSON Booleans
Fix bug that allowed Python’s JSON parser to parse a boolean JSON into a protobuf field of type int or float/double.
Generic Services Option
Disable code generation of python_generic_services, as generic services have
been deprecated since 2010. You can revert to legacy behavior by setting the
protoc flag --allow_legacy_generic_services. This flag will be removed in a
future breaking release.
Changes in PHP
Dropping PHP 8.2 Support
This release will drop PHP 8.2 as the minimum supported version and raise it to 8.3, as per the Foundational PHP Support Matrix.
UTF-8 Validity
Enforce UTF-8 validity in the upb json decoder.
Ruby
UTF-8 Validity
Enforce UTF-8 validity in the upb json decoder.
Conformance Tests
The Protocol Buffers project maintains an extensive conformance test suite to ensure consistent behavior across languages and runtimes. As part of our ongoing commitment to specification compliance and interoperability, we are actively working to address and implement a number of conformance test updates.
Due to the breadth of the test suite, detailed information regarding which specific conformance tests and behaviors are changing will be shared in a future release announcement.