1## gguf
 2
 3This is a Python package for writing binary files in the [GGUF](https://github.com/ggml-org/ggml/pull/302)
 4(GGML Universal File) format.
 5
 6See [convert_hf_to_gguf.py](https://github.com/ggml-org/llama.cpp/blob/master/convert_hf_to_gguf.py)
 7as an example for its usage.
 8
 9## Installation
10```sh
11pip install gguf
12```
13
14Optionally, you can install gguf with the extra 'gui' to enable the visual GGUF editor.
15```sh
16pip install gguf[gui]
17```
18
19## API Examples/Simple Tools
20
21[examples/writer.py](https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/examples/writer.py) — Generates `example.gguf` in the current directory to demonstrate generating a GGUF file. Note that this file cannot be used as a model.
22
23[examples/reader.py](https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/examples/reader.py) — Extracts and displays key-value pairs and tensor details from a GGUF file in a readable format.
24
25[gguf/scripts/gguf_dump.py](https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/gguf/scripts/gguf_dump.py) — Dumps a GGUF file's metadata to the console.
26
27[gguf/scripts/gguf_set_metadata.py](https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/gguf/scripts/gguf_set_metadata.py) — Allows changing simple metadata values in a GGUF file by key.
28
29[gguf/scripts/gguf_convert_endian.py](https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/gguf/scripts/gguf_convert_endian.py) — Allows converting the endianness of GGUF files.
30
31[gguf/scripts/gguf_new_metadata.py](https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/gguf/scripts/gguf_new_metadata.py) — Copies a GGUF file with added/modified/removed metadata values.
32
33[gguf/scripts/gguf_editor_gui.py](https://github.com/ggml-org/llama.cpp/blob/master/gguf-py/gguf/scripts/gguf_editor_gui.py) — Allows for viewing, editing, adding, or removing metadata values within a GGUF file as well as viewing its tensors with a Qt interface.
34
35## Development
36Maintainers who participate in development of this package are advised to install it in editable mode:
37
38```sh
39cd /path/to/llama.cpp/gguf-py
40
41pip install --editable .
42```
43
44**Note**: This may require to upgrade your Pip installation, with a message saying that editable installation currently requires `setup.py`.
45In this case, upgrade Pip to the latest:
46
47```sh
48pip install --upgrade pip
49```
50
51## Automatic publishing with CI
52
53There's a GitHub workflow to make a release automatically upon creation of tags in a specified format.
54
551. Bump the version in `pyproject.toml`.
562. Create a tag named `gguf-vx.x.x` where `x.x.x` is the semantic version number.
57
58```sh
59git tag -a gguf-v1.0.0 -m "Version 1.0 release"
60```
61
623. Push the tags.
63
64```sh
65git push origin --tags
66```
67
68## Manual publishing
69If you want to publish the package manually for any reason, you need to have `twine` and `build` installed:
70
71```sh
72pip install build twine
73```
74
75Then, follow these steps to release a new version:
76
771. Bump the version in `pyproject.toml`.
782. Build the package:
79
80```sh
81python -m build
82```
83
843. Upload the generated distribution archives:
85
86```sh
87python -m twine upload dist/*
88```
89
90## Run Unit Tests
91
92From root of this repository you can run this command to run all the unit tests
93
94```bash
95python -m unittest discover ./gguf-py -v
96```
97
98## TODO
99- [ ] Include conversion scripts as command line entry points in this package.