{"id":488,"library":"flatbuffers","title":"FlatBuffers","description":"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.","status":"active","version":"25.12.19","language":"python","source_language":"en","source_url":"https://github.com/google/flatbuffers","tags":["serialization","data-format","performance","no-parsing","zero-copy"],"install":[{"cmd":"pip install flatbuffers","lang":"bash","label":"Install FlatBuffers Python library"}],"dependencies":[],"imports":[{"note":"The core builder class for serialization.","symbol":"Builder","correct":"import flatbuffers\nbuilder = flatbuffers.Builder(0)"},{"note":"Schema-defined classes (e.g., `Monster`, `Vec3`, and their associated builder functions like `MonsterStart`, `MonsterAddName`, `MonsterEnd`) are generated by the `flatc` compiler into a Python module (e.g., `MyGame.Sample.py`). You import them from this generated module, not directly from the `flatbuffers` package.","wrong":"import flatbuffers.Monster","symbol":"Generated Classes (e.g., Monster, MonsterAddName, GetRootAsMonster)","correct":"from MyGame.Sample import Monster, MonsterAddName, GetRootAsMonster"}],"quickstart":{"code":"# 1. Define schema in 'monster.fbs' (run 'flatc --python monster.fbs' first)\n# monster.fbs content:\n# namespace MyGame.Sample;\n# struct Vec3 {\n#   x:float;\n#   y:float;\n#   z:float;\n# }\n# table Monster {\n#   pos:Vec3;\n#   hp:short = 100;\n#   name:string;\n#   inventory:[ubyte];\n# }\n# root_type Monster;\n\n# Assuming 'flatc --python monster.fbs' has been run,\n# which generates MyGame/Sample/Monster.py in the current directory.\n\nimport flatbuffers\nfrom MyGame.Sample import Monster, Vec3\n\n# --- Serialization ---\nbuilder = flatbuffers.Builder(0) # Initial buffer size, will grow as needed\n\n# 1. Create string for name (must be done before creating the Monster table)\nname_offset = builder.CreateString('Orc')\n\n# 2. Create Vector for inventory (must be done before creating the Monster table)\ninventory_data = [0, 1, 2, 3, 4]\nMonster.MonsterStartInventoryVector(builder, len(inventory_data))\nfor x in reversed(inventory_data): # FlatBuffers builds backwards\n    builder.PrependByte(x)\ninventory_offset = builder.EndVector()\n\n# 3. Create the Vec3 struct (can be done inline or before Monster table)\nVec3.CreateVec3(builder, 1.0, 2.0, 3.0)\npos_offset = builder.EndStruct()\n\n# 4. Start and populate the Monster table\nMonster.MonsterStart(builder)\nMonster.MonsterAddPos(builder, pos_offset)\nMonster.MonsterAddHp(builder, 80) # Override default hp=100\nMonster.MonsterAddName(builder, name_offset)\nMonster.MonsterAddInventory(builder, inventory_offset)\nmonster_offset = Monster.MonsterEnd(builder)\n\n# 5. Finish the buffer\nbuilder.Finish(monster_offset)\n\nbuffer = builder.Output()\nprint(f\"Serialized buffer (bytes): {buffer}\")\n\n# --- Deserialization ---\n# Get a 'view' of the root monster from the buffer\nmonster = Monster.GetRootAsMonster(buffer, 0)\n\n# Access fields\nprint(f\"Monster Name: {monster.Name().decode('utf-8')}\") # Strings need decoding\nprint(f\"Monster HP: {monster.Hp()}\")\n\npos = monster.Pos()\nprint(f\"Monster Position: ({pos.X()}, {pos.Y()}, {pos.Z()})\")\n\ninventory = []\nfor i in range(monster.InventoryLength()):\n    inventory.append(monster.Inventory(i))\nprint(f\"Monster Inventory: {inventory}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"After accessing a string field, apply `.decode('utf-8')`. Example: `monster.Name().decode('utf-8')`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions (schema changes)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:13:58.094Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the package using pip: `pip install flatbuffers` or for conda: `conda install -c conda-forge python-flatbuffers`.","cause":"The 'flatbuffers' Python package is not installed in the active Python environment or is incorrectly installed.","error":"ModuleNotFoundError: No module named 'flatbuffers'"},{"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.","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.","error":"AttributeError: 'Builder' object has no attribute 'CreateVectorOfTables'"},{"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`.","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.","error":"ImportError: cannot import name 'Monster' from 'Monster'"},{"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.","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.","error":"struct.error: pack_into requires a buffer of at least 4 bytes."},{"fix":"Encode the string to bytes (e.g., UTF-8) before passing it to the builder method: `my_string.encode('utf-8')`.","cause":"This error occurs when a Flatbuffers builder method, such as `PushBytes` or `PrependByte`, expects a `bytes` object but receives a Python `str` instead.","error":"TypeError: a bytes-like object is required, not 'str'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"18.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0.2,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"19.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"11.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.4,"disk_size":"11.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"17.5M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.2,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}