pygltflib

library1.16.5pypypi✓ verified 87d ago

pygltflib is a Python library for reading, writing, and managing 3D objects in the Khronos Group glTF (GL Transmission Format) and glTF2 formats. It supports the entire GLTF v2 specification, including materials, animations, and extensions, with all attributes being type-hinted. The library is actively maintained, with frequent updates addressing features and bug fixes.

serialization data

pip install pygltflib

package ↗homepage ↗

INSTALL

IMPORT

SIG · PYGLTFLIB

pygltflib

serializationpythonv1.16.5

Install

2.4s avg

Import

267ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.16.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.282s · 20.6MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.4s · import 0.252s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GLTF2

✓ from pygltflib import GLTF2

✗ import pygltflib; gltf = pygltflib.GLTF()

The primary class for GLTF 2.0 objects is GLTF2. Older patterns might use GLTF directly or attempt to instantiate an older version.

Scene

✓ from pygltflib import Scene

Node

✓ from pygltflib import Node

BufferFormat

✓ from pygltflib import BufferFormat

Used for converting between different buffer types (e.g., binary blob, data URI, external file).

glb2gltf

✓ from pygltflib.utils import glb2gltf

Utility function for converting GLB files to glTF files.

This quickstart demonstrates how to create a basic, empty glTF 2.0 file with a scene and a node, and then save it to disk. Real-world applications would involve populating the glTF object with meshes, materials, accessors, and buffer data. Ensure you have write permissions in the execution directory for the `gltf.save()` operation.

import os from pygltflib import GLTF2, Scene, Node # Create a new GLTF2 object gltf = GLTF2() # Create a scene scene = Scene(name="My_New_Scene") gltf.scenes.append(scene) gltf.scene = 0 # Set the default scene to the first one (index 0) # Create a simple node (e.g., an empty node) node = Node(name="My_Node") gltf.nodes.append(node) # Link the node to the scene scene.nodes.append(0) # Referencing the first node (index 0) # Define a filename output_filename = "my_simple_scene.gltf" # Save the GLTF file try: gltf.save(output_filename) print(f"GLTF file saved to {output_filename}") except Exception as e: print(f"Error saving GLTF file: {e}") # Clean up (optional) if os.path.exists(output_filename): os.remove(output_filename) print(f"Cleaned up {output_filename}")

Debug

Known issues

breakingSeveral deprecated attributes and classes were removed in `pygltflib` version 1.15.x. These include `AlphaMode`, `SparseAccessor`, and `MaterialTexture`.

fix

Replace `AlphaMode` with constants like `pygltflib.BLEND`, `MASK`, or `OPAQUE`. Use `AccessorSparseIndices` and `AccessorSparseValues` instead of `SparseAccessor`. Replace `MaterialTexture` with `TextureInfo`.

affects: >=1.15.0

breakingThe `GLTF2.load()` method now raises a `FileNotFoundError` if the specified file does not exist, rather than failing silently.

fix

Implement explicit file existence checks or wrap `GLTF2.load()` calls in `try-except FileNotFoundError` blocks to handle missing files gracefully.

affects: >=1.13.10

gotchaThe default value for `Material.alphaCutoff` changed from `0.5` to `None` in version 1.16.0. This might affect how materials are rendered if you relied on the implicit default for 'MASK' `alphaMode` materials.

fix

Explicitly set `material.alphaCutoff = 0.5` (or desired value) if your materials require it, especially for `alphaMode = 'MASK'` materials.

affects: >=1.16.0

gotchaHandling of image paths and buffer conversions, especially when working with GLB files, can be tricky. By default, images are loaded from/saved to the same directory as the GLTF file.

fix

Utilize `pygltflib.convert_buffers()` and `pygltflib.convert_images()` for explicit buffer and image data conversion (e.g., to/from external files, data URIs, or GLB binary blobs). For file-based conversions, consider `pygltflib.utils.glb2gltf` and `pygltflib.utils.gltf2glb`. Custom paths for image conversion can be specified using `GLTF.convert_images` with a `path` argument (from v1.13.10).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pygltflib'

The `pygltflib` library is not installed in your current Python environment.

fix

Install the library using pip: `pip install pygltflib`

FileNotFoundError: [Errno 2] No such file or directory: 'your_model.gltf'

The specified glTF or GLB file does not exist at the provided path, or the path is incorrect.

fix

Ensure the file path is correct and the file exists. You can add an explicit file existence check: 
```python
import os
from pygltflib import GLTF2

filename = 'your_model.gltf'
if os.path.exists(filename):
    gltf = GLTF2().load(filename)
else:
    print(f"Error: File not found at {filename}")
```

json.decoder.JSONDecodeError: Expecting value: line X column Y (char Z)

The glTF file (which is JSON-based) is malformed or contains invalid JSON syntax, preventing `pygltflib` from parsing it.

fix

Validate the glTF file using a glTF validator (e.g., Khronos glTF Validator online) or a JSON linter to identify and correct syntax errors. Ensure proper quoting (double quotes for keys and string values) and correct structure.

AttributeError: 'NoneType' object has no attribute 'some_attribute'

You are attempting to access an attribute (e.g., `baseColorTexture`, `bufferView`) on a glTF object that is `None`, indicating that the specific component or property was not present in the loaded glTF file.

fix

Before accessing optional attributes, check if the object or attribute itself is not `None`. For example, if accessing `baseColorTexture` on `pbrMetallicRoughness`:
```python
from pygltflib import GLTF2

gltf = GLTF2().load('your_model.gltf')
material = gltf.materials # Assuming a material exists

if material.pbrMetallicRoughness and material.pbrMetallicRoughness.baseColorTexture:
    # Access baseColorTexture safely
    texture_info = material.pbrMetallicRoughness.baseColorTexture
    # ... further processing
else:
    print("Material does not have a baseColorTexture.")
```

Upgrade

Version history

1.16.5latest on PyPI · released Jul 24, 2025

Audit

Dependencies

dataclasses-jsonrequiredRequired for (de)serialization of dataclasses to/from JSON.

numpyrequiredUsed for efficient handling of numerical buffer data within GLTF files. While not always strictly mandatory for basic operations, it's a core dependency for many use cases.

Agent activity

38 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/pygltflib/ ↗

homepagehttps://gitlab.com/dodgyville/pygltflib ↗