When Manual Download is Required
You’ll need to manually download models when:- The model requires accepting a license agreement
- The model is gated (requires Hugging Face authentication)
- Automatic download fails due to network issues
Prerequisites
Install Hugging Face CLI
Choose one method: Option 1: Using pipx (Recommended)Authenticate with Hugging Face
- Create a Hugging Face account at huggingface.co
- Generate an access token at huggingface.co/settings/tokens
- Log in via CLI:
Download Process
Step 1: Find the Model Directory
Izwi stores models in a specific location:Step 2: Download the Model
Use the Hugging Face CLI to download:<model-name> is the exact model ID from izwi list (for example Kokoro-82M).
Example for macOS:
Step 3: Verify the Download
Step 4: Load the Model
Downloading Specific Files
If you only need certain files (e.g., to save space):Chatterbox
Chatterbox-500M (about 3.2 GB) needs five files from Hugging Face
(ResembleAI/chatterbox at a pinned revision) and one from outside it: the
PerTh watermarker checkpoint, perth_net_250000.pth.tar, from Resemble AI’s
Perth repository on GitHub. Place all six files in the model’s directory:
a15bce457ebc53ce5e6c9c3f11df78cf7ee2bf9cdab0a798902135b4c4027670). Check a
copy you place yourself with shasum -a 256 (macOS) or sha256sum (Linux).
If the server runs with IZWI_CHATTERBOX_WATERMARK=false, the model loads
without the watermarker and the checkpoint is not needed.
Chatterbox-Multilingual-500M (about 3.3 GB) takes its own speech-token model
and tokenizer from the same repository and revision, with the English S3Gen,
voice encoder, default voice and the same PerTh checkpoint. Chinese also needs
the repository’s Cangjie table and two files of spacy-pkuseg’s word segmenter
from GitHub: its default model, spacy_ontonotes.zip (34,567,143 bytes,
SHA-256 b216e7f92de7ae285aeab8feba2faa8ea8216e5995ff6fb3d391cc8356db1bfe),
and its merge dictionary, saved as pkuseg_default.pkl (4,525,959 bytes,
SHA-256 3cf450d95719d51883fa49291302b9032372064d86805b130bb2ea0223196c67):
Resuming Interrupted Downloads
The Hugging Face CLI automatically resumes interrupted downloads. Just run the same command again.Using a Custom Cache Directory
By default, Hugging Face caches downloads in~/.cache/huggingface/. To use a different location:
Troubleshooting
”Access denied” or “401 Unauthorized”
-
Ensure you’re logged in:
- Check that you’ve accepted the model’s license on Hugging Face
- Verify your token has read permissions
Download is very slow
Try usinghf_transfer for faster downloads:
Model not detected by Izwi
- Verify the model is in the correct directory
- Check the folder name matches what Izwi expects
- Restart the Izwi server:
Disk space issues
Check available space before downloading:Next Steps
Maya1
Maya1-3B (about 6.7 GB) needs five files from Hugging Face
(maya-research/maya1 at a pinned revision) and the SNAC 24 kHz decoder from
hubertsiuzdak/snac_24khz, saved as snac_24khz.pth beside them:
4b8164cc6606bfa627f1a784734c1e539891518f1191ed9194fe1e3b9b4bff40).
Maya1-3B-GGUF (about 3.6 GB) takes the Q8_0 decoder from
mradermacher/maya1-GGUF, the config and tokenizer from maya-research/maya1,
and the same SNAC decoder:
Maya 2 Native
Maya2-Native-2.5B (about 5.5 GB) needs seven files from Hugging Face
(maya-research/maya2-native at a pinned revision), the Mimi codec’s config
and weights from kyutai/mimi, saved in mimi/, and SpeechBrain’s ECAPA
speaker encoder from speechbrain/spkrec-ecapa-voxceleb, saved in ecapa/:
Fish Audio Drama 3
FishAudio-Drama-3 (about 41.5 GB) needs the 24 files of fishaudio/drama-3
at a pinned revision: 15 safetensors shards, the codec (codec.pth, the same
file Fish S2 Pro ships), the configs, tokenizer, chat template, README.md
and LICENSE. Place them in the model’s directory:
izwi-artifact.json in the model’s directory;
every load then checks only that each file is present at its exact size and
that config.json has its pinned hash. So finish a copy you placed yourself
with Izwi’s download, or Download on the Models page:
izwi pull again.
With IZWI_OFFLINE set, Izwi contacts no one and downloads nothing, so it
cannot check a copy. Copy the whole FishAudio-Drama-3 directory from a
machine where Izwi downloaded or checked it, izwi-artifact.json included.
To check a copy by hand first, use shasum -a 256 (macOS) or sha256sum
(Linux):
The 24 files total 41,502,569,692 bytes. The weights are licensed under the
Fish Audio Community License v1.0 (the repository’s
LICENSE); see
Models.