gguf-editor

README

GGUF Editor

GGUF Editor is a terminal user interface for inspecting and editing the metadata stored in GGUF model files. It reads the GGUF header, metadata records and tensor directory, then lets you change scalar metadata values without loading the model tensors into memory.

The tool is intended for small, deliberate metadata changes on existing GGUF files. When you save, it writes a new file named modified_<original-name> next to the source file and streams the original tensor data into the output file.

What it does

• Opens GGUF v2 and v3 files.
• Shows metadata keys, value types and display values in a keyboard-driven table.
• Shows the GGUF version, tensor count and source file size.
• Edits scalar metadata values such as strings, booleans, integers and floats.
• Adds new scalar metadata keys.
• Deletes metadata keys.
• Preserves tensor data by copying it from the original file instead of reading it all into memory.

Array metadata values are displayed but cannot currently be edited directly.

Installation

You need Go installed.

go install github.com/andydixon/gguf-editor@latest

For local development from this repository:

go build .

Usage

gguf-editor path/to/model.gguf

If you built it locally:

./gguf-editor path/to/model.gguf

Inside the interface:

• e or Enter edits the selected scalar value.
• a adds a new scalar metadata key.
• d deletes the selected key.
• s saves to modified_<original-name>.
• q quits.
• Esc cancels the current edit, add or confirmation dialogue.

Saving never overwrites the input file. For example, opening model.gguf and pressing s writes modified_model.gguf in the same directory.

Implementation notes

The GGUF parser in gguf.go reads the magic value, version, tensor count, metadata count, metadata key-value pairs and tensor descriptors using little-endian binary reads. Tensor payload data is left on disk until save time.

The terminal interface in main.go is built with Charmbracelet Bubble Tea, Bubbles and Lip Gloss. It keeps a dirty flag for unsaved changes and rebuilds the metadata table after edits, additions and deletions.

Licence

This project is licensed under the GNU General Public License version 3. See LICENSE for the full licence text.