Distribute Python type hints

Open
#30,731 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@zhangskz is already working on this.

Since Oct 15, 2026.

Assessment

This issue has not been assessed yet.

Description

feature request

What language does this apply to?
It's for the Python protobuf package.

Describe the problem you are trying to solve.
We want to be able to fully type check the generated proto code, while using the latest releases.

Without it we get the following errors while using mypy (and similar erros when using other type checkers)

myproto_pb2.pyi:3: error: Library stubs not installed for "google.protobuf"  [import-untyped]
myproto_pb2.pyi:4: error: Library stubs not installed for "google.protobuf.internal"  [import-untyped]
myproto_pb2.pyi:4: note: Hint: "python3 -m pip install types-protobuf"
myproto_pb2.pyi:4: note: (or run "mypy --install-types" to install all missing stub packages)
myproto_pb2.pyi:4: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
myproto_pb2.pyi:13: error: Class cannot use "EnumTypeWrapper" as a metaclass (has type "Any")  [metaclass]
myproto_pb2.pyi:24: error: Class cannot subclass "Message" (has type "Any")  [misc]
myproto_pb2.pyi:32: error: Class cannot subclass "Message" (has type "Any")  [misc]
myproto_pb2.pyi:56: error: Class cannot subclass "Message" (has type "Any")  [misc]
myproto_pb2.pyi:58: error: Class cannot subclass "Message" (has type "Any")  [misc]
myproto_pb2.pyi:109: error: Class cannot subclass "Message" (has type "Any")  [misc]
myproto_pb2.pyi:117: error: Class cannot subclass "Message" (has type "Any")  [misc]
Found 9 errors in 1 file (checked 2 source files)

Describe the solution you'd like
The python package protobuf should include built in annotations using PEP 561.

Describe alternatives you've considered
The currently suggested alternative it to use the package types-protobuf from typeshed. However, at the time of writing (Oct 15th 2026), the latest released version is for version 7.35.1, while protobuf 7.36 has been available for almost 2 months. See the PR where they add support for the new version.

Also note that support for 7.35.1 was added on August 20th in this PR, more than two months later of the protobuf release.

Additional context
Note that this issue is related to https://github.com/protocolbuffers/protobuf/issues/9918

Dominant language
C++
Stars
72.2k
Forks
16.4k
Avg merge
1d 8h
Merged PRs (30d)
342

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from protocolbuffers/protobuf

All issues in protocolbuffers/protobuf

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.