gguf

What it is and what it does

gguf is a Python library for reading and writing files in the GGUF binary format, which is the standard container for machine learning models used by GGML and llama.cpp. It provides both a programmatic API for working with GGUF files in code and command-line tools for inspecting, editing, and converting model metadata and tensors. The package depends on numpy for tensor operations, pyyaml for configuration, requests for network operations, and tqdm for progress reporting.

The library is part of the llama.cpp ecosystem and is actively maintained. It includes utilities to dump metadata, modify key-value pairs, convert file endianness, and optionally a Qt-based GUI editor for visual inspection and editing of GGUF files. It's designed for developers working with GGML-based inference engines who need to programmatically manipulate model files or integrate GGUF handling into their workflows.

Use it for:

• Convert Hugging Face models to GGUF format for use with llama.cpp and other GGML-based inference engines.
• Inspect and extract metadata, tensor names, and structure from existing GGUF model files.
• Modify model metadata (name, description, hyperparameters) in GGUF files without rebuilding them.
• Automate GGUF file generation and manipulation in model training or deployment pipelines.
• Debug or validate GGUF file integrity and endianness across different systems.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Reads and writes binary files in the GGUF (GGML Universal File) format, commonly used for storing machine learning models compatible with GGML-based tools like llama.cpp.

Yes. The package has low install friction, active maintenance, no known vulnerabilities, permissive licensing, and strong adoption in the GGML/llama.cpp ecosystem. Install it if you need to work with GGUF model files programmatically or via command-line tools.

Install

gguf on PyPI

pip install gguf

uv add gguf

poetry add gguf

Installing gguf

Before you install

Installs cleanly with low friction—a pure Python wheel with four common dependencies (numpy, pyyaml, requests, tqdm). Maintained actively with recent releases and no known vulnerabilities.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute this package freely in both open and closed projects without restriction.

Quickstart

pip install gguf

from gguf import GGUFReader, GGUFWriter
import numpy as np

# Read a GGUF file
reader = GGUFReader('model.gguf')
metadata = reader.get_field('general.name')

# Write a GGUF file
writer = GGUFWriter('output.gguf')
writer.add_tensor('tensor_name', np.array([1.0, 2.0, 3.0]))

Requires Python 3.10 or later.

Verify before relying

• Whether the GUI extra dependency list and installation steps are current.
• Performance characteristics when handling large model files.
• Compatibility guarantees with specific GGML or llama.cpp versions.

Package facts

Evidence: gguf-0.19.0-py3-none-any.whl

Keywords: ggml, gguf, llama.cpp

Tags

More Artificial Intelligence packages