Self-HostingAIGen AI

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.

Resemble AI logo, the maker of Chatterbox

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.
WhatValue
Version usedSource 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
LicenceMIT, for the code and the four model repositories (read on the GitHub page and the Hugging Face model cards, October 2026)
Time neededAbout 30 minutes plus the model download (3 to 4 GB per model)
DiskAt least 10 GB free is a sensible target (the community server's own advice)
PortsNone for the library. 8004 for the optional community server
Official docshttps://github.com/resemble-ai/chatterbox

Tip: Do not install with pip install chatterbox-tts if 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.

How Chatterbox works: you give text and a 10 second voice clip with the speaker's consent, a Chatterbox model runs on your own CPU, GPU or Mac chip and speaks the text, Perth adds a hidden watermark, and a WAV file is saved on your disk, with a side note that the model is downloaded once from Hugging Face and an optional community server can wrap it

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.

SystemWhat you needNotes
LinuxPython 3.10 or newer (3.11 recommended), git, about 10 GB freeNVIDIA GPU optional. The default PyPI build of PyTorch 2.6.0 on Linux brings CUDA support
WindowsPython 3.11, git, PowerShell 7The PyPI PyTorch wheel for Windows is CPU only (204 MB). For an NVIDIA GPU use the CUDA wheel in Step 1
MacPython 3.11 (Homebrew), git, TerminalApple 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:

Run in terminalbash
python3 --version
git --version
Run in terminalpowershell
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-tts yet

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#

Run in terminalbash
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)#

Codepowershell
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:

Run in terminalpowershell
pip install torch==2.6.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124

Then, for everyone:

Run in terminalpowershell
pip install -e .\source

If PowerShell refuses to run Activate.ps1, allow scripts for your user once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Mac (Terminal)#

Run in terminalbash
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:

Run in terminalbash
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#

Run in terminalbash
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)#

Codepowershell
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):

Run in terminalbash
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 gives ModuleNotFoundError: 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_weight of 0 to 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:

Run in terminalbash
cd ~/chatterbox-tts/work
source ../.venv/bin/activate
python speak.py my-voice.wav

Windows (PowerShell)#

Codepowershell
Set-Location "$HOME\chatterbox-tts\work"
..\.venv\Scripts\Activate.ps1
python speak.py .\my-voice.wav

Mac (Terminal)#

Same commands as Linux:

Run in terminalbash
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#

Run in terminalbash
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)#

Codepowershell
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#

Run in terminalbash
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)#

Codepowershell
$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:

Run in terminalbash
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 (default Emily.wav). Mounting an empty voices folder 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#

Run in terminalbash
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)#

Codepowershell
$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/models first. This server has no such address (issue #173), so those apps may refuse to connect although speech works.

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):

DoDo not
Get the speaker's permission, ideally in writing, saying what the voice may be used forClone a colleague or a public figure "just to test"
Keep clips private (a voice clip is personal data). Delete them when the permission endsTrick people with a cloned voice (fake calls, fake approvals)
Tell listeners when a voice is syntheticRemove or hide the watermark

What leaves your machine#

Almost nothing, and this is the main reason to self-host it.

WhenWhat goes out
InstallPython packages from PyPI and the Perth library from GitHub
First runThe 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 speechNothing. It runs on your CPU or GPU
Official Gradio demo appsA 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.

File contentyaml
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 caseWhat Caddy doesWhat you do
Public domainGets and renews a free Let's Encrypt certificate by itselfPoint a DNS A record at the server and open ports 80 and 443
Home only, no domainMakes its own local certificate with tls internalTrust 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:

File contenttext
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):

File contenttext
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, then sudo systemctl reload caddy.
  • Windows (PowerShell): winget install CaddyServer.Caddy, save the Caddyfile in a folder, then caddy run --config Caddyfile there.
  • Mac: brew install caddy, save the Caddyfile, then caddy run --config Caddyfile.
  • Docker: use caddy:2.11.7 (the current release when this guide was checked) in a separate folder ~/docker_volumes/caddy with ports 80 and 443, the Caddyfile and a ./data:/data volume. Put the TTS service on the same proxy network without a published port, and write reverse_proxy chatterbox-tts-server:8004 in 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.

ControlHow
NetworkPublish the server port on 127.0.0.1 only. Never forward port 8004 on your router
LoginThe server has none. Use the Caddy or Traefik basic auth above, or keep it local
SecretsNone are needed. If you set HF_TOKEN, keep it in a .env file with chmod 600
Demo appsNever run the official Gradio demos with the share=True line left in (see below)
Supply chainThe 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#

MistakeWhy it happensDo this instead
Installing with pip install chatterbox-tts and then running the README's nano=True or t3_model="v3" examplesThe 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 neitherInstall from source as in Step 1
Naming your script chatterbox.pyPython 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 areBoth end in .launch(share=True). Gradio then creates a public link that anyone can open for about a weekDo 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.0The 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 textsTurbo 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 askingThe tool makes it easy, and the watermark does not give permissionGet permission first, keep it on record, see "Using it responsibly"
Asking an AI assistant for the setup and trusting the answerAssistants 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#

ProblemSolution
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 WindowsThe default PyPI wheel is CPU only. Install the cu124 build from Step 1
RuntimeError: expected scalar type Double but found Float with a voice clipKnown 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 modelKnown bug in the community server (issue #168). Restart the container
An app cannot connect and the log shows a 404 on /v1/modelsThe 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:

Run in terminalbash
cd ~/chatterbox-tts/source && git fetch && git checkout <NEW_COMMIT>
source ../.venv/bin/activate && pip install -e .
Codepowershell
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:

File contentbash
#!/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:

Codepowershell
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.

Run in terminalbash
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.

ModelParametersLanguagesDownload
Nano110MEnglishabout 3.0 GB
Turbo350MEnglishabout 4.0 GB
Multilingual V3500M23+about 3.2 GB
Original500MEnglishabout 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_size and POST /api/unload to free memory. They help the GPU images more than the CPU image in Step 5.
  • Monitor: docker stats chatterbox-tts-server for the container, nvidia-smi for 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.