Metadata-Version: 2.1
Name: gguf-editor
Version: 0.0.3
Summary: GGUF metadata/tensor editor with a built-in quantizer — browser GUI via `python -m gguf_editor`
Author-Email: gguf <info@gguf.us>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Project-URL: Repository, https://github.com/gguf-org/editor
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# gguf-editor

GGUF metadata/tensor editor with a built-in quantizer, packaged for Python.
The editor GUI runs in your browser against a local server — files are opened
straight from disk, so multi-GB models are never uploaded or fully loaded into
memory. The quantization engine is the standalone C/C++ quantizer (no ggml
dependency), compiled during `pip install` and bundled with the package.

## Install

```bash
pip install gguf-editor
```

Building the bundled quantizer requires a C/C++ toolchain and CMake ≥ 3.15
(on Windows: MSVC Build Tools). GPU accelerators are opt-in at build time:

```bash
CMAKE_ARGS="-DQUANTIZER_CUDA=ON"  pip install gguf-editor   # NVIDIA (CUDA toolkit)
CMAKE_ARGS="-DQUANTIZER_HIP=ON"   pip install gguf-editor   # AMD (ROCm/HIP)
CMAKE_ARGS="-DQUANTIZER_METAL=ON" pip install gguf-editor   # Apple (macOS)
```

## Usage

```bash
python -m gguf_editor                 # launch the editor GUI in the browser
python -m gguf_editor model.gguf      # …opening a file right away
python -m gguf_editor --port 8642 --no-browser
```

Editor features (as in the desktop editor / chrome extension):

- inspect and edit metadata (all value types incl. arrays), add/delete keys
- rename, delete, reorder (drag), merge tensors; add zero-filled tensors;
  import tensors from another GGUF
- find & replace across tensor names (literal or regex)
- per-tensor precision changes and/or a batch weight type — on save the file
  is rebuilt with your edits and then converted by the quantizer into a
  single output file
- streams tensor data disk-to-disk on save with live progress

CLI quantizer (mirrors the standalone `quantizer` binary):

```bash
python -m gguf_editor quantize -m model-f16.gguf -o model-q4_k.gguf --type q4_k
python -m gguf_editor quantize -m model.safetensors -o model-q8_0.gguf --type q8_0
python -m gguf_editor quantize -m model.gguf -o out.gguf \
    --tensor-type-rules "attention.*weight=q4_k" --device auto
python -m gguf_editor devices
```

Supported types: `f32 f16 bf16 q4_0 q4_1 q5_0 q5_1 q8_0 q1_0 q2_k q3_k q4_k
q5_k q6_k iq1_s iq1_m iq2_xxs iq2_xs iq2_s iq3_xxs iq3_s iq4_nl iq4_xs tq1_0
tq2_0 mxfp4 nvfp4`. Inputs may be GGUF or safetensors (auto-detected;
multi-part safetensors are merged automatically).

## Python API

```python
from gguf_editor import gguf, quantizer

parsed = gguf.parse_file("model.gguf")           # header-only parse
print(parsed.version, len(parsed.tensor_infos))

quantizer.quantize("model-f16.gguf", "model-q4_k.gguf", default_type="q4_k")
```

## License

MIT
