---
id: gguf
version: "0.19.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# gguf — Read and write ML models in GGUF for GGML

License: permissive · Maintenance: active · Downloads: 6.9M/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

gguf file format reader writer, ggml model serialization, llama.cpp model conversion, gguf metadata editor, ml model binary format, gguf tensor handling, convert models to gguf, model-serialization, llama-cpp, ml-tooling

[View on SkillFed](https://skillfed.io/packages/gguf) · [View on PyPI](https://pypi.org/project/gguf/)