Chatterbox TTS: Self-Hosted Voice Cloning Text-to-Speech (Linux, Windows, Mac)
Before you start
- 22 min read
Boxes marked Run in terminal are what you type; plain text explains why. Check what you need first

What you get in one minute#
Chatterbox is an open-source text-to-speech model from Resemble AI that runs on your own computer and can copy a voice from a short recording, so your text and your voice clips never have to be sent to a cloud service.

Logo: Resemble AI, the maker of Chatterbox, as shown in the official README (github.com/resemble-ai/chatterbox)
Chatterbox is a Python library, not a ready-made server. That is the first thing to know. You install it, run a short script, and get a WAV file. If you want a web page or an OpenAI-style /v1/audio/speech address on top, you need a community project, and this guide shows one clearly labelled as community.
At a glance:
- Cloning needs a clean recording of about 10 seconds. You must have the speaker's permission.
- Every file it makes carries a hidden Perth watermark, built in.
- Models: Turbo (350M, English, tags such as
[laugh]), Nano (110M, English, made for CPUs), Multilingual V3 (500M, 23+ languages) and the original (500M, English). - Nothing is uploaded while it speaks. The only download is the model, once, from Hugging Face.
- There is no official Docker image and no official server. We say so and never invent one.
| What | Value |
|---|---|
| Version used | Source code of the official repository as of 21 July 2026 (commit 5de7a54). The PyPI package chatterbox-tts is 0.1.7 (March 2026) and is older than that |
| Licence | MIT, for the code and the four model repositories (read on the GitHub page and the Hugging Face model cards, October 2026) |
| Time needed | About 30 minutes plus the model download (3 to 4 GB per model) |
| Disk | At least 10 GB free is a sensible target (the community server's own advice) |
| Ports | None for the library. 8004 for the optional community server |
| Official docs | https://github.com/resemble-ai/chatterbox |
Tip: Do not install with
pip install chatterbox-ttsif you want Nano or Multilingual V3. The package on PyPI is older than those models, and the README examples for them fail with it. Step 1 installs from source for that reason.
How it fits together#
You give Chatterbox some text and, if you want a cloned voice, a short clip. It speaks on your own hardware, adds a watermark and saves a WAV file.
The optional community server in Steps 5 and 6 sits in front of the same model. It takes an HTTP request instead of a script call.
Before you start#
You need Python, git and enough disk for the model. A GPU helps a lot but is not required.
The developers state one tested setup: Python 3.11 on Debian 11. Windows and Mac are not listed as tested (Mac only has an example file and mps support in the code). Follow the same steps there, but treat them as community-proven.
| System | What you need | Notes |
|---|---|---|
| Linux | Python 3.10 or newer (3.11 recommended), git, about 10 GB free | NVIDIA GPU optional. The default PyPI build of PyTorch 2.6.0 on Linux brings CUDA support |
| Windows | Python 3.11, git, PowerShell 7 | The PyPI PyTorch wheel for Windows is CPU only (204 MB). For an NVIDIA GPU use the CUDA wheel in Step 1 |
| Mac | Python 3.11 (Homebrew), git, Terminal | Apple chips use mps. No NVIDIA support on Mac |
There is no official video-memory (VRAM) table. The README only says Turbo needs "less compute and VRAM than our previous models" and that Nano runs "3x faster than realtime on 8 CPU cores". We do not invent numbers.
Check your tools:
python3 --version git --version
py -3.11 --version git --version
Checklist:
- [ ] Python 3.10 or newer, git installed
- [ ] 10 GB of free disk
- [ ] You have a recording of a voice you may clone (or you will start with the built-in voice)
- [ ] Nothing important is in
~/chatterbox-ttsyet
Tested on 2026-10-30: Linux = not run, Windows = not run, Mac = not run. The commands were checked against the developers' README, example files and source code (see Sources).
Step 1: Install Chatterbox from source#
Create a folder and a Python virtual environment, then install the official repository at a pinned commit.
We pin the commit so that your install matches this guide. The source folder is named source and the scripts live in a separate work folder, so Python never mistakes a folder called chatterbox for the library.
Linux#
mkdir -p ~/chatterbox-tts/work && cd ~/chatterbox-tts git clone https://github.com/resemble-ai/chatterbox.git source git -C source checkout 5de7a54 python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -e ./source
On Debian or Ubuntu, if venv complains, install python3-venv first. The install also fetches Perth (the watermark library) from GitHub, so git must be on your PATH.
Windows (PowerShell)#
New-Item -ItemType Directory -Force "$HOME\chatterbox-tts\work" | Out-Null Set-Location "$HOME\chatterbox-tts" git clone https://github.com/resemble-ai/chatterbox.git source git -C source checkout 5de7a54 py -3.11 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip
Have an NVIDIA GPU? Install the CUDA build of PyTorch first. The PyTorch index lists torch-2.6.0+cu124 for Windows and Python 3.11:
pip install torch==2.6.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
Then, for everyone:
pip install -e .\source
If PowerShell refuses to run Activate.ps1, allow scripts for your user once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
Mac (Terminal)#
brew install [email protected] git mkdir -p ~/chatterbox-tts/work && cd ~/chatterbox-tts git clone https://github.com/resemble-ai/chatterbox.git source git -C source checkout 5de7a54 python3.11 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -e ./source
Check it worked:
python -c "import torch; from chatterbox.tts_turbo import ChatterboxTurboTTS; print('torch', torch.__version__, 'cuda', torch.cuda.is_available())"
Expected shape (from the pinned dependencies, not a recorded run): torch 2.6.0 ... and cuda True on an NVIDIA machine, cuda False on a CPU or Mac. The library does not print a version, so a clean import is the test. Potential issue: dependency conflicts were reported many times (issues #77, #243, #367, #390). Use a fresh virtual environment.
Step 2: Make your first voice (no cloning yet)#
Write a short script and let Chatterbox Turbo speak with its built-in voice. The first run downloads the model.
Start without a clone: it proves the install works and needs nobody's permission. The script picks CUDA, Apple mps or CPU by itself. The Turbo model is about 4 GB; the files come from Hugging Face on the first run only and are cached afterwards.
Linux#
cd ~/chatterbox-tts/work
cat > speak.py <<'EOF'
import sys
import torch
import torchaudio as ta
from chatterbox.tts_turbo import ChatterboxTurboTTS
if torch.cuda.is_available():
device = "cuda"
elif torch.backends.mps.is_available():
device = "mps"
else:
device = "cpu"
print("Using device:", device)
model = ChatterboxTurboTTS.from_pretrained(device=device)
text = "Hello from my own computer. [chuckle] This voice never left the machine."
wav = model.generate(text)
ta.save("hello-default.wav", wav, model.sr)
print("Saved hello-default.wav")
if len(sys.argv) > 1:
wav = model.generate(text, audio_prompt_path=sys.argv[1])
ta.save("hello-cloned.wav", wav, model.sr)
print("Saved hello-cloned.wav")
EOF
python speak.py
Windows (PowerShell)#
Set-Location "$HOME\chatterbox-tts\work"
@'
import sys
import torch
import torchaudio as ta
from chatterbox.tts_turbo import ChatterboxTurboTTS
if torch.cuda.is_available():
device = "cuda"
elif torch.backends.mps.is_available():
device = "mps"
else:
device = "cpu"
print("Using device:", device)
model = ChatterboxTurboTTS.from_pretrained(device=device)
text = "Hello from my own computer. [chuckle] This voice never left the machine."
wav = model.generate(text)
ta.save("hello-default.wav", wav, model.sr)
print("Saved hello-default.wav")
if len(sys.argv) > 1:
wav = model.generate(text, audio_prompt_path=sys.argv[1])
ta.save("hello-cloned.wav", wav, model.sr)
print("Saved hello-cloned.wav")
'@ | Set-Content speak.py -Encoding utf8
python speak.py
Mac (Terminal)#
Same commands as Linux (keep the virtual environment active):
cd ~/chatterbox-tts/work # create speak.py exactly as in the Linux step, then: python speak.py
Check it worked: the script prints Using device: ..., then Saved hello-default.wav, and you can play hello-default.wav in any player. Words in square brackets, such as [chuckle], are Turbo's paralinguistic tags: the model acts them out. The README names [cough], [laugh] and [chuckle].
Tip: Name your own script anything except
chatterbox.py. A file with that name hides the real library and givesModuleNotFoundError: No module named 'chatterbox.tts'; 'chatterbox' is not a package(issue #160).
Potential issue: one user reported a very slow first run on an M1 Mac (issue #191); we give no timing.
Step 3: Clone a voice you have permission to use#
Give the script a clean WAV recording of about 10 seconds and Chatterbox copies the voice.
Read "Using it responsibly" below first. The rule is short: get the speaker's clear permission, ideally in writing, before you clone any voice that is not your own.
Tips for the reference clip, from the README and a maintainer reply in issue #39:
- About 10 seconds, WAV, 24 kHz or higher, one speaker, no background noise.
- The clip's language should match the text, or its accent leaks into the result (the README suggests
cfg_weightof0to reduce that). - The defaults (
exaggeration=0.5,cfg_weight=0.5) suit most text; they belong to the original and Multilingual models.
Linux#
Put your clip in the work folder as my-voice.wav, then:
cd ~/chatterbox-tts/work source ../.venv/bin/activate python speak.py my-voice.wav
Windows (PowerShell)#
Set-Location "$HOME\chatterbox-tts\work" ..\.venv\Scripts\Activate.ps1 python speak.py .\my-voice.wav
Mac (Terminal)#
Same commands as Linux:
cd ~/chatterbox-tts/work source ../.venv/bin/activate python speak.py my-voice.wav
Check it worked: hello-cloned.wav exists and sounds like the speaker. If it sounds off, try a cleaner clip before changing any settings.
Tip: Keep each text to a few sentences. Users report that Turbo hallucinates above roughly 350 characters (issue #424). Split long text and join the files afterwards.
Step 4: Check the watermark#
Prove that your file carries the Perth watermark, using the detector from the README.
Chatterbox adds the watermark inside generate(), so you do not switch it on. Check a file like this:
Linux#
cd ~/chatterbox-tts/work
cat > check_mark.py <<'EOF'
import sys
import librosa
import perth
audio, sr = librosa.load(sys.argv[1], sr=None)
watermarker = perth.PerthImplicitWatermarker()
print("Extracted watermark:", watermarker.get_watermark(audio, sample_rate=sr))
EOF
python check_mark.py hello-default.wav
Windows (PowerShell)#
Set-Location "$HOME\chatterbox-tts\work"
@'
import sys
import librosa
import perth
audio, sr = librosa.load(sys.argv[1], sr=None)
watermarker = perth.PerthImplicitWatermarker()
print("Extracted watermark:", watermarker.get_watermark(audio, sample_rate=sr))
'@ | Set-Content check_mark.py -Encoding utf8
python check_mark.py hello-default.wav
Mac (Terminal)#
Same commands as Linux.
Check it worked: the README says the answer is 0.0 (no watermark) or 1.0 (watermarked). Expect 1.0 for your file. Resemble AI says the mark survives MP3 compression and common edits with "nearly 100% detection accuracy". That is the vendor's claim; we did not measure it.
Step 5: Add a community OpenAI-style server (optional)#
If you want a web page and an OpenAI-style speech address, run the community project Chatterbox-TTS-Server in Docker on the CPU.
This part is not official. It is a separate project: https://github.com/devnen/Chatterbox-TTS-Server (MIT, v2.0.0 from May 2026). It builds from source; we found no image with a documented tag, so we use none. It runs its own copy of the Chatterbox code from March 2026, so it offers the original, Turbo and Multilingual V2, but not Nano or V3.
Safety first: the server listens on all addresses and has no login (use_auth in its config is only a placeholder). So we bind the port to your own machine and add a login in the HTTPS step.
Linux#
mkdir -p ~/docker_volumes/chatterbox-tts/{hf_cache,backups} && cd ~/docker_volumes/chatterbox-tts
git clone --branch v2.0.0 --depth 1 https://github.com/devnen/Chatterbox-TTS-Server.git server
cat > compose.yaml <<'EOF'
services:
chatterbox-tts-server:
build:
context: ./server
dockerfile: Dockerfile.cpu
container_name: chatterbox-tts-server
restart: unless-stopped
ports:
- "127.0.0.1:8004:8004"
volumes:
- ./server/config.yaml:/app/config.yaml
- ./server/voices:/app/voices
- ./server/reference_audio:/app/reference_audio
- ./server/outputs:/app/outputs
- ./server/logs:/app/logs
- ./hf_cache:/app/hf_cache
environment:
- HF_HUB_ENABLE_HF_TRANSFER=1
EOF
docker compose up -d --build
Windows (PowerShell)#
$d = "$HOME\docker_volumes\chatterbox-tts"
New-Item -ItemType Directory -Force "$d\hf_cache","$d\backups" | Out-Null
Set-Location $d
git clone --branch v2.0.0 --depth 1 https://github.com/devnen/Chatterbox-TTS-Server.git server
@'
services:
chatterbox-tts-server:
build:
context: ./server
dockerfile: Dockerfile.cpu
container_name: chatterbox-tts-server
restart: unless-stopped
ports:
- "127.0.0.1:8004:8004"
volumes:
- ./server/config.yaml:/app/config.yaml
- ./server/voices:/app/voices
- ./server/reference_audio:/app/reference_audio
- ./server/outputs:/app/outputs
- ./server/logs:/app/logs
- ./hf_cache:/app/hf_cache
environment:
- HF_HUB_ENABLE_HF_TRANSFER=1
'@ | Set-Content compose.yaml -Encoding utf8
docker compose up -d --build
Mac (Terminal)#
Same commands as Linux. Docker Desktop on a Mac runs the CPU image only: a container cannot use the Apple chip (mps). The author documents a non-Docker route for Apple chips ("Option 4"). We did not test the Docker route on a Mac, and its author does not describe it.
Check it worked: the first build downloads PyTorch and the first start downloads the model, so give it several minutes (we have no measured time). Follow the log, then ask the server about its model:
docker compose logs -f --tail 50 curl -s http://127.0.0.1:8004/api/model-info
On Windows use curl.exe instead of curl. The server's config.yaml selects Turbo by default (repo_id: chatterbox-turbo). The API documentation page is at http://127.0.0.1:8004/docs and the web page at http://127.0.0.1:8004.
Tip: The compose file here mounts
./server/voices, not an empty folder. The server ships more than 20 ready-made voices (defaultEmily.wav). Mounting an emptyvoicesfolder would hide them.
Step 6: Call it like OpenAI's speech API#
Send a JSON request to /v1/audio/speech and save the audio.
The voice field is the file name of a voice in voices/ or in reference_audio/. The model field is required by the request format; any text works. We read this from the server's source code at the v2.0.0 tag.
Linux#
curl -s http://127.0.0.1:8004/v1/audio/speech \
-H "Content-Type: application/json" \
-d '{"model":"chatterbox","input":"Hello from my own server.","voice":"Emily.wav","response_format":"wav"}' \
--output hello-server.wav
Windows (PowerShell)#
$body = @{ model = "chatterbox"; input = "Hello from my own server."; voice = "Emily.wav"; response_format = "wav" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8004/v1/audio/speech -ContentType "application/json" -Body $body -OutFile hello-server.wav
Mac (Terminal)#
Same commands as Linux.
Check it worked: hello-server.wav plays. To use a cloned voice, copy a consented clip into ~/docker_volumes/chatterbox-tts/server/reference_audio/ and use its file name as voice. List what is available with curl -s http://127.0.0.1:8004/v1/audio/voices.
Tip: Some OpenAI-compatible apps check
GET /v1/modelsfirst. This server has no such address (issue #173), so those apps may refuse to connect although speech works.
Using it responsibly: consent and the watermark#
Cloning a voice is something you do with a person's permission, and the watermark is a safety net, not a licence.
What the official project says: the README states "Don't use this model to do bad things", and every generated file carries the Perth watermark. It says nothing more about consent. The rules below are DIY Lab Hub's own practice, not a quote and not legal advice (laws differ by country):
| Do | Do not |
|---|---|
| Get the speaker's permission, ideally in writing, saying what the voice may be used for | Clone a colleague or a public figure "just to test" |
| Keep clips private (a voice clip is personal data). Delete them when the permission ends | Trick people with a cloned voice (fake calls, fake approvals) |
| Tell listeners when a voice is synthetic | Remove or hide the watermark |
What leaves your machine#
Almost nothing, and this is the main reason to self-host it.
| When | What goes out |
|---|---|
| Install | Python packages from PyPI and the Perth library from GitHub |
| First run | The model files are downloaded from Hugging Face. The models are not gated, so no account or token is needed (the loader reads HF_TOKEN only if you set it) |
| Generating speech | Nothing. It runs on your CPU or GPU |
| Official Gradio demo apps | A public link. See the mistake table below |
Gradio, behind the demo apps, has an analytics switch (GRADIO_ANALYTICS_ENABLED, default True). We did not read what it sends: set it to False if you use the demos.
Put it behind HTTPS (with or without Traefik)#
This applies to the optional community server in Step 5 only, and only if other devices will reach it. The server has no login, so HTTPS must come with a password.
If you only use the scripts on one computer, skip this section.
With Traefik#
On a server with a domain, let Traefik handle HTTPS and remove the published port.
This assumes Traefik v3 already runs with the Docker provider, shares a network called proxy, has an entrypoint called https and a certificate for your hostname. Replace ports: in the service with the lines below.
services:
chatterbox-tts-server:
build:
context: ./server
dockerfile: Dockerfile.cpu
container_name: chatterbox-tts-server
restart: unless-stopped
volumes:
- ./server/config.yaml:/app/config.yaml
- ./server/voices:/app/voices
- ./server/reference_audio:/app/reference_audio
- ./server/outputs:/app/outputs
- ./server/logs:/app/logs
- ./hf_cache:/app/hf_cache
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy"
- "traefik.http.routers.tts.rule=Host(`tts.<your-domain>`)"
- "traefik.http.routers.tts.entrypoints=https"
- "traefik.http.routers.tts.tls=true"
- "traefik.http.routers.tts.middlewares=tts-auth"
- "traefik.http.middlewares.tts-auth.basicauth.users=<USER>:<HASH_WITH_DOLLARS_DOUBLED>"
- "traefik.http.services.tts.loadbalancer.server.port=8004"
networks:
proxy:
external: true
Create the network once with docker network create proxy. Make the user and hash with htpasswd -nB <USER>; in a Compose file every $ in the hash is written $$ (Traefik docs). Add traefik.http.routers.tts.tls.certresolver=<your-resolver> if you use an ACME resolver.
Check it worked: curl -I https://tts.<your-domain>/docs answers 401 without a password and 200 with one (curl -I -u <USER> https://tts.<your-domain>/docs).
Without Traefik: Caddy#
Choose Caddy if you have no Traefik yet and run one small server. It gets the certificate for you and can ask for a password.
| Your case | What Caddy does | What you do |
|---|---|---|
| Public domain | Gets and renews a free Let's Encrypt certificate by itself | Point a DNS A record at the server and open ports 80 and 443 |
| Home only, no domain | Makes its own local certificate with tls internal | Trust Caddy's root certificate on every device that opens the page |
First make a password hash. Caddy does not accept plain passwords (Caddy documentation): run caddy hash-password and paste the result below (with Docker: docker run --rm -it caddy:2.11.7 caddy hash-password).
Public domain:
tts.example.com {
basic_auth {
<USER> <HASH_FROM_CADDY>
}
reverse_proxy localhost:8004
}
Home only (use a name your own DNS or hosts file points at this machine; .home.arpa is reserved for home networks):
tts.home.arpa {
tls internal
basic_auth {
<USER> <HASH_FROM_CADDY>
}
reverse_proxy localhost:8004
}
Keep the 127.0.0.1:8004:8004 port from Step 5. Caddy on the same machine reaches it there.
Trust the root certificate (home only). On the Caddy machine run caddy trust. On every other device copy pki/authorities/local/root.crt from Caddy's data folder and import it:
- Linux (Debian or Ubuntu):
sudo cp root.crt /usr/local/share/ca-certificates/caddy-root.crt && sudo update-ca-certificates - Windows (PowerShell as administrator):
certutil -addstore -f ROOT root.crt - Mac:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain root.crt
Caddy's data folder is /var/lib/caddy/.local/share/caddy for the Linux service, %AppData%\Caddy on Windows and ~/Library/Application Support/Caddy on Mac.
Run Caddy. Pick one:
- Linux: install from the official repository on the Caddy install page, put your site in
/etc/caddy/Caddyfile, thensudo systemctl reload caddy. - Windows (PowerShell):
winget install CaddyServer.Caddy, save the Caddyfile in a folder, thencaddy run --config Caddyfilethere. - Mac:
brew install caddy, save the Caddyfile, thencaddy run --config Caddyfile. - Docker: use
caddy:2.11.7(the current release when this guide was checked) in a separate folder~/docker_volumes/caddywith ports 80 and 443, the Caddyfile and a./data:/datavolume. Put the TTS service on the sameproxynetwork without a published port, and writereverse_proxy chatterbox-tts-server:8004in the Caddyfile.
Check it worked: curl -I https://tts.example.com/docs answers 401 and curl -I -u <USER> https://tts.example.com/docs answers HTTP/2 200.
Security and testing#
The library is local and quiet. The server is the part that needs care.
| Control | How |
|---|---|
| Network | Publish the server port on 127.0.0.1 only. Never forward port 8004 on your router |
| Login | The server has none. Use the Caddy or Traefik basic auth above, or keep it local |
| Secrets | None are needed. If you set HF_TOKEN, keep it in a .env file with chmod 600 |
| Demo apps | Never run the official Gradio demos with the share=True line left in (see below) |
| Supply chain | The community Dockerfile installs its Chatterbox fork from master without a pin. Rebuild only when you intend to |
Tests: docker compose ps shows the container running, docker logs chatterbox-tts-server --tail 50 shows no errors, curl -s http://127.0.0.1:8004/api/model-info answers, and a call to /v1/audio/speech returns a playable file. Run check_mark.py on a file to see the watermark.
Common mistakes#
| Mistake | Why it happens | Do this instead |
|---|---|---|
Installing with pip install chatterbox-tts and then running the README's nano=True or t3_model="v3" examples | The PyPI package (0.1.7, March 2026) is older than Nano (July 2026) and V3 (May and June 2026). We opened the wheel and found neither | Install from source as in Step 1 |
Naming your script chatterbox.py | Python imports your file instead of the library: No module named 'chatterbox.tts'; 'chatterbox' is not a package (issue #160) | Rename the script, delete the __pycache__ folder beside it |
Running the official gradio_tts_app.py or gradio_tts_turbo_app.py as they are | Both end in .launch(share=True). Gradio then creates a public link that anyone can open for about a week | Do not run them as they are. Use speak.py, or change share=True to share=False first |
| Using an RTX 50 series card with the pinned PyTorch 2.6.0 | The error says CUDA capability sm_120 is not supported (issue #344) | Use a newer PyTorch built for CUDA 12.8 (users report 2.9.0 works), or the community server's CUDA 12.8 option, driver 570 or newer |
| Pasting a whole chapter into one call, or one-word texts | Turbo hallucinates above about 350 characters (issue #424), short texts such as "Yes" give gibberish (issue #97), one Web UI cut output at 40 seconds (issue #76) | Use a few sentences per call and join the audio files |
| Cloning a voice without asking | The tool makes it easy, and the watermark does not give permission | Get permission first, keep it on record, see "Using it responsibly" |
| Asking an AI assistant for the setup and trusting the answer | Assistants invent an official Docker image, a chatterbox serve command, a built-in OpenAI endpoint, or a VRAM table. None of these exist in the official repository (checked 2026-10-30) | Use the commands in this guide, which come from the README and the source. Ask the assistant to name the file in the repository that proves a claim |
Troubleshooting#
| Problem | Solution |
|---|---|
TypeError: 'NoneType' object is not callable in from_pretrained() | Reported when installed with uv pip install; it worked when built from source. Use the pip steps above (issue #198) |
torch.cuda.is_available() is False on Windows | The default PyPI wheel is CPU only. Install the cu124 build from Step 1 |
RuntimeError: expected scalar type Double but found Float with a voice clip | Known with numpy 2 on Python 3.13 and newer (issue #499). Use Python 3.11 |
TTS engine failed to synthesize audio for chunk 1 on a Mac (server) | Reported with NotImplementedError: Output channels > 65536 not supported at the MPS device. The error text suggests PYTORCH_ENABLE_MPS_FALLBACK=1 (server issue #180) |
| The server answers 503 after you unload the model | Known bug in the community server (issue #168). Restart the container |
An app cannot connect and the log shows a 404 on /v1/models | The server has no such address (issue #173) |
Known bugs#
The official issue list is long, with many install conflicts on newer Python versions. Check https://github.com/resemble-ai/chatterbox/issues before you spend an evening on a strange error.
Diagnostics: docker logs chatterbox-tts-server --tail 100, docker compose ps, docker inspect chatterbox-tts-server.
Updates and backups#
There is no auto-update. Move the pinned commit on purpose, and back up what you cannot download again.
GitHub shows only the tag v0.1.2 (June 2025) and PyPI is behind the source, so read the commit list, then:
cd ~/chatterbox-tts/source && git fetch && git checkout <NEW_COMMIT> source ../.venv/bin/activate && pip install -e .
Set-Location "$HOME\chatterbox-tts\source"; git fetch; git checkout <NEW_COMMIT> ..\.venv\Scripts\Activate.ps1; pip install -e .
For the community server, change the tag in the git clone (for example to a newer release) and run docker compose up -d --build.
What to back up: your reference clips, the server's config.yaml and compose.yaml. The models can be downloaded again. Backup script (Linux and Mac), saved as ~/docker_volumes/chatterbox-tts/backup.sh:
#!/usr/bin/env bash set -e cd ~/docker_volumes mkdir -p chatterbox-tts/backups tar czf chatterbox-tts/backups/chatterbox-tts-$(date +%F).tgz \ chatterbox-tts/compose.yaml chatterbox-tts/server/config.yaml \ chatterbox-tts/server/reference_audio
Schedule it at 03:00 with crontab -e: 0 3 * * * bash ~/docker_volumes/chatterbox-tts/backup.sh. The archive holds voice clips, so keep it private. On Windows, use Task Scheduler with this PowerShell line:
Compress-Archive -Path "$HOME\docker_volumes\chatterbox-tts\compose.yaml","$HOME\docker_volumes\chatterbox-tts\server\config.yaml","$HOME\docker_volumes\chatterbox-tts\server\reference_audio" -DestinationPath "$HOME\docker_volumes\chatterbox-tts\backups\chatterbox-tts-$(Get-Date -Format yyyy-MM-dd).zip" -Force
Restore test (Linux and Mac): unpack into a scratch folder and look at the files.
mkdir -p /tmp/restore-test && tar xzf ~/docker_volumes/chatterbox-tts/backups/chatterbox-tts-*.tgz -C /tmp/restore-test ls /tmp/restore-test/chatterbox-tts
Performance and resources#
We did not measure speed or memory. These are the official statements and the knobs that exist.
| Model | Parameters | Languages | Download |
|---|---|---|---|
| Nano | 110M | English | about 3.0 GB |
| Turbo | 350M | English | about 4.0 GB |
| Multilingual V3 | 500M | 23+ | about 3.2 GB |
| Original | 500M | English | about 3.2 GB |
Load Nano with ChatterboxTurboTTS.from_pretrained(device=..., nano=True) and V3 with ChatterboxMultilingualTTS.from_pretrained(device=..., t3_model="v3").
Download sizes are the file sizes listed on Hugging Face (October 2026). Official claims: Turbo uses less compute and VRAM than earlier models; Nano runs 3x faster than realtime on 8 CPU cores. Nothing more.
- Pick the smallest model that is good enough. Nano on a CPU is the cheapest start.
- Load once. A script that loads the model once and speaks many texts beats many runs.
- Community server:
TTS_BF16=on(its README: about 40% more throughput on bf16 GPUs),chunk_sizeandPOST /api/unloadto free memory. They help the GPU images more than the CPU image in Step 5. - Monitor:
docker stats chatterbox-tts-serverfor the container,nvidia-smifor an NVIDIA GPU.
FAQ#
Is there an official Docker image or server? No. We checked the official repository on 2026-10-30: it holds a Python package and demo scripts. The server in this guide is a community project.
Can I use it for commercial work? The code and models are MIT licensed. That does not cover permission from the person whose voice you clone.
Does it need a GPU? No. Nano is made for CPUs and Turbo runs on a CPU too, only slower. We did not measure speed.
Is my voice sent anywhere? Not by Chatterbox while it speaks. The model is downloaded once. The one trap is the official Gradio demos with share=True, which publish a public link.
Sources#
Read on 2026-10-30:
- Official repository, README,
pyproject.toml, example files and source: https://github.com/resemble-ai/chatterbox - PyPI package: https://pypi.org/project/chatterbox-tts/
- Model cards: Turbo, Nano, original and Multilingual
- Perth watermark library: https://github.com/resemble-ai/perth
- Community server (not official): https://github.com/devnen/Chatterbox-TTS-Server
- Gradio, sharing your app: https://www.gradio.app/guides/sharing-your-app
- PyTorch CUDA 12.4 wheels: https://download.pytorch.org/whl/cu124/torch/
- Caddy: https://caddyserver.com/docs/caddyfile/directives/basic_auth and https://caddyserver.com/docs/install
- Traefik basic auth: https://doc.traefik.io/traefik/reference/routing-configuration/http/middlewares/basicauth/
- Issues quoted: #39, #76, #97, #160, #191, #198, #344, #424 and #499 in the official repository; #168, #173 and #180 in the community server repository
Checked against the official docs on 2026-10-30.