FlatBuffers

raw JSON →
25.12.19 verified Tue May 12 auth: no python install: verified quickstart: stale

FlatBuffers is an open-source, cross-platform serialization library from Google for Python and other languages. It enables efficient and language-independent ways to serialize and deserialize data, focusing on speed and memory efficiency by allowing direct access to serialized data without parsing. The Python library is actively maintained with frequent releases, currently at version 25.12.19, often updating multiple times a month.

pip install flatbuffers

Common errors

error ModuleNotFoundError: No module named 'flatbuffers' ↓
cause The 'flatbuffers' Python package is not installed in the active Python environment or is incorrectly installed.
fix
Install the package using pip: pip install flatbuffers or for conda: conda install -c conda-forge python-flatbuffers.
error AttributeError: 'Builder' object has no attribute 'CreateVectorOfTables' ↓
cause The installed FlatBuffers Python library version (often from PyPI) is outdated or does not include the 'CreateVectorOfTables' method, while the 'flatc' compiler (which generates code using this method) might be newer.
fix
Update the 'flatbuffers' Python package to the latest version using pip install --upgrade flatbuffers, and ensure your 'flatc' compiler version is compatible with the installed Python library.
error ImportError: cannot import name 'Monster' from 'Monster' ↓
cause When using the '--python-typing' flag with schemas containing self-referential types or nested namespaces, the 'flatc' compiler can generate Python files with incorrect or recursive relative import statements.
fix
Manually correct the generated import statements in the affected Python files, or upgrade to a newer version of the 'flatc' compiler and 'flatbuffers' Python library, as this is a known bug that gets patched. For example, changing from Monster import Monster to import Monster and then referring to Monster.Monster.
error struct.error: pack_into requires a buffer of at least 4 bytes. ↓
cause This error often indicates that the FlatBuffer 'Builder' object was not properly finalized with `builder.Finish()` after all data has been added, or that nested objects were not built and 'ended' in the correct 'inside-out' order.
fix
Ensure builder.Finish(root_offset) is called exactly once on the root object's offset after all objects and their nested components have been properly built and their respective EndObject() or EndVector() methods have been invoked.
error TypeError: a bytes-like object is required, not 'str' ↓
cause This error occurs when a Flatbuffers builder method, such as `PushBytes` or `PrependByte`, expects a `bytes` object but receives a Python `str` instead.
fix
Encode the string to bytes (e.g., UTF-8) before passing it to the builder method: my_string.encode('utf-8').

Warnings

gotcha FlatBuffers uses an 'inside-out' or 'depth-first' construction rule: any nested objects (strings, vectors, other tables, or structs within tables/vectors) must be serialized first, and their offsets obtained, before they can be added to their parent object. Attempting to add an uncreated nested object will result in an invalid buffer. ↓
fix Always serialize leaf-level data (strings, raw scalar vectors, structs) and then child tables before their parent tables. Pass the returned offsets (e.g., from `builder.CreateString()` or `ChildTableEnd()`) to the parent's `Add` methods.
gotcha When deserializing string fields in Python, they are returned as `bytes` objects. You must explicitly call `.decode('utf-8')` (or another appropriate encoding) to convert them into standard Python `str` objects. ↓
fix After accessing a string field, apply `.decode('utf-8')`. Example: `monster.Name().decode('utf-8')`.
gotcha FlatBuffers are designed for efficient reads and compact storage, not for easy in-place modification or creation of data in Python. If you need to change data in a FlatBuffer, you typically have to rebuild the entire buffer, which can be computationally expensive for frequent updates. ↓
fix For mutable data, consider using a standard Python data structure, converting it to FlatBuffers for storage/transmission, and then rebuilding it entirely if changes are needed. FlatBuffers shine when data is mostly static or read-heavy.
breaking Schema evolution requires careful management to maintain forward and backward compatibility. Removing fields is prohibited; instead, mark them `deprecated`. New fields must be added at the end of a table definition unless explicit `id` attributes are used for all fields. Changing types or default values can also break compatibility. ↓
fix Consult the FlatBuffers 'Evolution' documentation. Use the `deprecated` attribute for unused fields and always append new fields. If `id` attributes are used, ensure they are consistent across schema versions.
gotcha The `flatc` compiler (written in C++) is essential for generating the Python classes from `.fbs` schema files. It needs to be installed and accessible in your system's PATH. Version mismatches between the `flatc` compiler used to generate the code and the `flatbuffers` Python runtime library can lead to hard-to-debug issues. ↓
fix Ensure `flatc` is installed and in your PATH. Ideally, use a `flatc` compiler version that is consistent with or close to the `flatbuffers` Python library version you are using. Check the FlatBuffers GitHub releases for `flatc` binaries and the changelog for versioning notes.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) - - 0.01s 18.0M
3.10 slim (glibc) - - 0.00s 18M
3.11 alpine (musl) - - 0.01s 19.9M
3.11 slim (glibc) - - 0.01s 20M
3.12 alpine (musl) - - 0.01s 11.7M
3.12 slim (glibc) - - 0.01s 12M
3.13 alpine (musl) - - 0.01s 11.4M
3.13 slim (glibc) - - 0.01s 12M
3.9 alpine (musl) - - 0.01s 17.5M
3.9 slim (glibc) - - 0.01s 18M

Imports

Quickstart stale last tested: 2026-04-23

This quickstart demonstrates how to define a FlatBuffers schema, compile it using `flatc` to generate Python classes, and then use these generated classes along with the `flatbuffers.Builder` to serialize a 'Monster' object into a byte buffer. It also shows how to deserialize the buffer and access its fields. Note that you must first save the schema to a file (e.g., `monster.fbs`) and run the `flatc --python monster.fbs` command in your terminal for the Python imports to work. The `flatc` compiler needs to be installed separately.

# 1. Define schema in 'monster.fbs' (run 'flatc --python monster.fbs' first)
# monster.fbs content:
# namespace MyGame.Sample;
# struct Vec3 {
#   x:float;
#   y:float;
#   z:float;
# }
# table Monster {
#   pos:Vec3;
#   hp:short = 100;
#   name:string;
#   inventory:[ubyte];
# }
# root_type Monster;

# Assuming 'flatc --python monster.fbs' has been run,
# which generates MyGame/Sample/Monster.py in the current directory.

import flatbuffers
from MyGame.Sample import Monster, Vec3

# --- Serialization ---
builder = flatbuffers.Builder(0) # Initial buffer size, will grow as needed

# 1. Create string for name (must be done before creating the Monster table)
name_offset = builder.CreateString('Orc')

# 2. Create Vector for inventory (must be done before creating the Monster table)
inventory_data = [0, 1, 2, 3, 4]
Monster.MonsterStartInventoryVector(builder, len(inventory_data))
for x in reversed(inventory_data): # FlatBuffers builds backwards
    builder.PrependByte(x)
inventory_offset = builder.EndVector()

# 3. Create the Vec3 struct (can be done inline or before Monster table)
Vec3.CreateVec3(builder, 1.0, 2.0, 3.0)
pos_offset = builder.EndStruct()

# 4. Start and populate the Monster table
Monster.MonsterStart(builder)
Monster.MonsterAddPos(builder, pos_offset)
Monster.MonsterAddHp(builder, 80) # Override default hp=100
Monster.MonsterAddName(builder, name_offset)
Monster.MonsterAddInventory(builder, inventory_offset)
monster_offset = Monster.MonsterEnd(builder)

# 5. Finish the buffer
builder.Finish(monster_offset)

buffer = builder.Output()
print(f"Serialized buffer (bytes): {buffer}")

# --- Deserialization ---
# Get a 'view' of the root monster from the buffer
monster = Monster.GetRootAsMonster(buffer, 0)

# Access fields
print(f"Monster Name: {monster.Name().decode('utf-8')}") # Strings need decoding
print(f"Monster HP: {monster.Hp()}")

pos = monster.Pos()
print(f"Monster Position: ({pos.X()}, {pos.Y()}, {pos.Z()})")

inventory = []
for i in range(monster.InventoryLength()):
    inventory.append(monster.Inventory(i))
print(f"Monster Inventory: {inventory}")
last verified Tue May 12
next check Fri Jun 26