githubkit is too big — split type stubs into separate package?

[jarenere]

So i've been using githubkit in a lambda function and ran into the size limit pretty quick. The package is about ~108 MB installed, and like 90% of that is generated code under githubkit/versions/.

here's roughly where the space goes:

$ ncdu ...
--- /private/tmp/lambda-build/processor-deps/python/githubkit/versions 
                                                  /..
   25.5 MiB [###################################] /ghec_v2022_11_28
   25.4 MiB [################################## ] /ghec_v2026_03_10
   22.6 MiB [###############################    ] /v2022_11_28
   22.6 MiB [###############################    ] /v2026_03_10
    1.7 MiB [##                                 ] /latest
   20.0 KiB [                                   ]  versions.lock
    4.0 KiB [                                   ]  rest.py
    4.0 KiB [                                   ]  webhooks.py
    4.0 KiB [                                   ]  __init__.py

The types/ directories alone are ~41 MB of TypedDict stubs that are never actually used at runtime — every import is behind TYPE_CHECKING or is_lazy_disabled(). Thats a lot of dead weight for production deployments.

proposal

Option 1: extract type stubs into githubkit-types

Split the TypedDict stubs into a seperate githubkit-types package using PEP420 implicit namespace packages. Fully backward compatible, i think that no code changes needed.

main package (githubkit):

• Exclude githubkit/versions/*/types/ and githubkit/versions/latest/types.py from the wheel via source-exclude
• Add a [types] optional dependency
• Update [all] extra to include githubkit-types
• No runtime code changes — type imports are already behind TYPE_CHECKING

new package (githubkit-types):

• Only the types/ directories
• Uses uv_build with namespace = true to overlay into githubkit.versions.*.types
• Only depends on typing-extensions

install options:

pip install githubkit              
pip install githubkit[types] 

Option 2: optional API version extras

taking it further, could also make individual API versions optional:

pip install githubkit[v2026_03_10]         # core + only 2026-03-10
pip install githubkit[ghec_v2022_11_28]    # core + only GHEC 2022-11-28
pip install githubkit[all-versions]        # everything (current behaviour)

This one is more work tho since models and rest modules are used at runtime, so it would need:

• Runtime fallback with clear ImportError mesages when a version isn't installed
• Codegen changes to output each version as a seperate sub-package

Option 3:

Option 1 + Option 2

For now i will try to remove some folders from the wheel, and cross one's fingers, xD

---

If you're open to any of these changes, i'd be happy to help with the implementation

[yanyongyu]

I'm afraid moving the types into a separate package would bring breaking changes. These TypedDict classes can be used by users to write type annotations and construct API input data in their own projects — even though we only import them behind TYPE_CHECKING in the library code, splitting them out would break runtime imports for existing users.

Making API versions optional via extra dependencies seems like a good idea, which can effectively solve the package size issue for production deployments. But, we may need to change the project structure and touch a fair amount of code (like codegen, fallback, lazy importing, etc..)

[yanyongyu]

Another option is to compress the lib into a zip archive and you can directly import the package from this zip file. Python has builtin support by zipimport importer. You just need to inject the zip file path into sys.path.

[jarenere]

i think that zipimport approach will works, building the layer with the dependencies and the zip, but in practice it gets messy — you end up with code like:

try:
    import githubkit
except ImportError:
    import sys
    sys.path.append("/opt/libs.zip")
    import githubkit

or:

import os
if os.environ.get("AWS_LAMBDA_FUNCTION_NAME"):
    import sys
    sys.path.append("/opt/libs.zip")
import githubkit

or even:

import importlib.util
if importlib.util.find_spec("githubkit") is None:
    import sys
    sys.path.append("/opt/libs.zip")
import githubkit

There's also the cold start problem: Lambda gives you ~15s for init, and zipimport has to decompress modules on every cold start without being able to cache .pyc files (the zip is read-only). With ~97 MB of version modules that adds up, especially combined with other dependencies.

And the core problem still remains outside Lambda: in Docker/K8s (where small images are the norm), you're paying for ~97 MB of version modules — both in image size and decompression time — that you'll never use.

I think it's a really good feature to add, although it might involve breaking some contract (new major version)

I have something half-finished, not yet real tested https://github.com/jarenere/githubkit/tree/feat/split_versions

[yanyongyu]

I've decided to split the versioned schemas into a standalone new package. It allows installing specific API versions via extras, and users can also upgrade githubkit and the schemas independently to maintain compatibility and functionality.

[yanyongyu]

I’ve just submitted PR #303, which implements the new schema logic. It’s now ready for testing.

You can install the githubkit and schema packages located under the packages folder.
I’ve also added fallback logic, so i believe no code changes are required on your side (warnings on fallback).

Feel free to share any feedback!