Some models require manual download from Hugging Face due to licensing requirements or access restrictions. This guide covers the general process.

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)
Option 2: Using pip

Authenticate with Hugging Face

  1. Create a Hugging Face account at huggingface.co
  2. Generate an access token at huggingface.co/settings/tokens
  3. Log in via CLI:
Enter your token when prompted.

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:
Example for Linux:

Step 3: Verify the Download

The model should appear in the list.

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:
When Izwi downloads the checkpoint itself, it checks the size (37,429,684 bytes) and SHA-256 (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):
Izwi reads the dictionary as the one pickled string it holds and never unpickles it.

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”

  1. Ensure you’re logged in:
  2. Check that you’ve accepted the model’s license on Hugging Face
  3. Verify your token has read permissions

Download is very slow

Try using hf_transfer for faster downloads:

Model not detected by Izwi

  1. Verify the model is in the correct directory
  2. Check the folder name matches what Izwi expects
  3. Restart the Izwi server:

Disk space issues

Check available space before downloading:
Large models can be 10+ GB. Ensure you have enough free space.

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:
When Izwi downloads the decoder itself, it checks the size (79,488,254 bytes) and SHA-256 (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/:
When Izwi downloads the last three files itself, it checks each one’s size and SHA-256:

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 lists the model as downloaded only once every file has been checked against its pinned SHA-256. Its own download does that once, after the last file lands, and records it in 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:
It reads the revision’s file list from Hugging Face, finds every file already at its size, downloads nothing, hashes each file once (a few minutes for 41.5 GB) and marks the model downloaded. A file that does not match its pin is named in the error: delete it and run 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.