This is a Python package for writing binary files in the GGUF (GGML Universal File) format. It allows reading and writing of ML models, including metadata and tensors, for efficient inference with GGML-based frameworks like llama.cpp. The current version is 0.18.0, released on February 27, 2026, and the project has a regular release cadence, often aligned with updates from the upstream llama.cpp project.
pip install ggufVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to create a simple GGUF file containing metadata and a tensor, and then how to read its header, key-value metadata, and tensor information using the `gguf` Python library. It highlights the core `GGUFWriter` and `GGUFReader` classes.
Ensure that GGUF files are created with a compatible version and that the `gguf` Python library is up-to-date to handle the latest GGUF format features. For model conversions, use the recommended `llama.cpp` conversion scripts.
If encountering `ImportError: cannot import name '...' from 'scripts'`, check for `gguf` as a potential cause. A workaround might involve virtual environments or renaming conflicting local modules, or checking for a `gguf` package update that resolves this structure.
Always ensure the chat template and `eos` (end-of-sequence) tokens configured in the GGUF file match those expected by the specific model and its inference engine. Consult the model's documentation for correct template usage.
Regularly update the `gguf` Python package to the latest version, especially when working with recently released GGUF models or `llama.cpp` builds, to ensure compatibility with the most current format features.
Exercise caution and verify the source and content of GGUF files, especially those from untrusted origins. Review embedded chat templates and system instructions before deploying models in sensitive applications.
Review the `gguf` library's documentation and example scripts for the correct way to write GGUF files and their key-value metadata. Common methods for writing metadata include `writer.write_header()` and `writer.write_kv_data()`, or higher-level utility functions provided by the library for complete file generation.
Ensure that necessary system build tools are installed in the environment before attempting to install the Python package. For Alpine Linux, this often means running `apk add cmake pkgconfig build-base`. For Debian/Ubuntu, use `apt-get install cmake pkg-config build-essential`.
Install the package using pip: `pip install gguf` or `python -m pip install gguf` if using an embedded Python environment.
Update the `gguf` package to the latest version: `pip install --upgrade gguf`. If the issue persists, ensure the `gguf` library version is compatible with the specific conversion script or framework you are using, or consult the `gguf` project's documentation for API changes.
Inspect the GGUF file's metadata using `gguf.GGUFReader` to verify the actual keys present and adjust your code to use the correct metadata keys, or ensure the model conversion process correctly populates the expected metadata fields.
Verify the compatibility between the GGUF model file and the model architecture definition you are using. If converting, ensure the conversion script correctly handles tensor shapes and types for the specific model. Sometimes, using a different version of the conversion tool or the target framework (e.g., `transformers`) can resolve such incompatibilities.