fix(setup): pin dev venv to Python 3.12 to not break setup step

CHANGELOG.md

@@ -7,6 +7,25 @@
 
 ## [Unreleased]
 
+### Developer Experience
+
+- **`just setup` now pins the Python venv to 3.12.** Setup preferred `python3.12` when
+  it found one but silently fell back to 3.13 or bare `python3`, so a machine on
+  3.13/3.14 built a venv that then failed to install dependencies capped below 3.13
+  (kokoro, misaki, numpy, numba) with `Could not find a version that satisfies the
+  requirement`. Setup now requires 3.12, and recreates a venv that is on the wrong
+  version or whose pip doesn't run, so a stale or half-built one heals on the next
+  `just setup` rather than needing a manual `rm -rf backend/venv`. Reporting 3.12
+  isn't enough for an interpreter to be chosen — it has to actually build a working
+  venv, so setup falls through to the next candidate when one can't (Debian packages
+  `ensurepip` separately as `python3.12-venv`; current Homebrew `python@3.12` bottles
+  carry a `pyexpat` that won't load on macOS 26). If none work it exits with the
+  install command for your platform instead of failing deep inside pip. Windows
+  resolves it through the `py -3.12` launcher, since Windows installers don't create
+  a `python3.12` command.
+- **The 3.12 requirement is now machine-readable.** `backend/pyproject.toml`
+  declares `requires-python = ">=3.12,<3.13"` rather than an open-ended `>=3.12`,
+  so the constraint the docs describe is the one tooling resolves against.
 ### Linux
 
 - **ROCm setup works on Linux AMD systems.** Docker ROCm builds now keep PyTorch

CONTRIBUTING.md

@@ -18,9 +18,11 @@ Thank you for your interest in contributing to Voicebox! This document provides
   curl -fsSL https://bun.sh/install | bash
   ```
 
-- **[Python 3.11+](https://python.org)** - For backend development
+- **[Python 3.12](https://python.org)** - For backend development. Voicebox pins its
+  virtual environment to 3.12 to match CI, because some dependencies have no 3.13
+  release yet. On Debian/Ubuntu also install `python3.12-venv`.
   ```bash
-  python --version  # Should be 3.11 or higher
+  python3.12 --version  # Should be 3.12.x
   ```
 
 - **[Rust](https://rustup.rs)** - For Tauri desktop app (installed automatically by Tauri CLI)
@@ -44,7 +46,7 @@ just dev     # starts backend + desktop app
 ```
 
 `just setup` handles everything automatically, including:
-- Creating a Python virtual environment
+- Creating a Python virtual environment pinned to 3.12 (recreating it if an existing venv is on the wrong version)
 - Installing Python dependencies (with CUDA PyTorch on Windows if an NVIDIA GPU is detected)
 - Installing MLX dependencies on Apple Silicon
 - Installing JavaScript dependencies
@@ -67,7 +69,7 @@ just --list        # see all available commands
 
 #### Windows Notes
 
-The justfile works natively on Windows via PowerShell. No WSL or Git Bash required. On Windows with an NVIDIA GPU, `just setup` automatically installs CUDA-enabled PyTorch for GPU acceleration.
+The justfile works natively on Windows via PowerShell. No WSL or Git Bash required. On Windows with an NVIDIA GPU, `just setup` automatically installs CUDA-enabled PyTorch for GPU acceleration. Python 3.12 is located via the `py -3.12` launcher; install it with `winget install -e --id Python.Python.3.12` if it's missing.
 
 ### Model Downloads
 
@@ -363,7 +365,7 @@ See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/
 
 **Quick fixes:**
 
-- **Backend won't start:** Check Python version (3.11+), ensure venv is activated, install dependencies
+- **Backend won't start:** Check Python version (must be 3.12), ensure venv is activated, install dependencies
 - **Tauri build fails:** Ensure Rust is installed, clean build with `cd tauri/src-tauri && cargo clean`
 - **OpenAPI client generation fails:** Ensure backend is running, check `curl http://localhost:17493/openapi.json`
 

README.md

@@ -417,7 +417,7 @@ just dev     # starts backend + desktop app
 
 Install [just](https://github.com/casey/just): `brew install just` or `cargo install just`. Run `just --list` to see all commands.
 
-**Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.11+](https://python.org), [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/), and [Xcode](https://developer.apple.com/xcode/) on macOS.
+**Prerequisites:** [Bun](https://bun.sh), [Rust](https://rustup.rs), [Python 3.12](https://python.org), [Tauri Prerequisites](https://v2.tauri.app/start/prerequisites/), and [Xcode](https://developer.apple.com/xcode/) on macOS.
 
 The repo ships a pre-wired `.mcp.json` at the root — running Claude Code inside this checkout picks up the Voicebox MCP tools automatically once the dev app is running.
 

backend/pyproject.toml

@@ -1,7 +1,12 @@
 [project]
 name = "voicebox-backend"
 version = "0.2.3"
-requires-python = ">=3.12"
+# This is the one place the Python pin is explained; the justfile and docs point here
+# rather than restating it. The upper bound is real, not defensive: requirements.txt
+# currently pulls in kokoro and misaki (which declare requires-python <3.13) plus
+# numpy<2 and numba<0.61 (no 3.13 wheels), so `pip install -r requirements.txt` fails
+# outright on a later interpreter. Recheck those four before raising it.
+requires-python = ">=3.12,<3.13"
 
 # ---------------------------------------------------------------------------
 # Ruff – linter + formatter

docs/content/docs/developer/architecture.mdx

@@ -48,7 +48,7 @@ These two layers communicate via HTTP on `localhost:17493`, with the frontend ma
 
 ### Tech Stack
 
-- **Framework**: FastAPI (Python 3.11+)
+- **Framework**: FastAPI (Python 3.12)
 - **TTS Engines**: Qwen3-TTS, Qwen CustomVoice, LuxTTS, Chatterbox, Chatterbox Turbo, TADA, Kokoro
 - **Transcription**: Whisper (PyTorch or MLX-Whisper)
 - **Inference Backends**: MLX (Apple Silicon), PyTorch (CUDA / ROCm / XPU / DirectML / CPU)

docs/content/docs/developer/setup.mdx

@@ -32,11 +32,13 @@ Ensure you have these installed:
     curl -fsSL https://bun.sh/install | bash
     ```
   </Card>
-  <Card title="Python 3.11+" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
+  <Card title="Python 3.12" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2L2 7l10 5 10-5-10-5z"/><path d="M2 17l10 5 10-5"/><path d="M2 12l10 5 10-5"/></svg>}>
     [Download Python](https://python.org)
     ```bash
-    python --version
+    python3.12 --version  # macOS/Linux — should be 3.12.x
+    py -3.12 --version    # Windows
     ```
+    Voicebox pins its venv to 3.12 to match CI, because some dependencies have no 3.13 release yet. On Debian/Ubuntu also install `python3.12-venv`.
   </Card>
   <Card title="Rust" icon={<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="m6 9 6 6 6-6"/></svg>}>
     [Install Rust](https://rustup.rs)
@@ -65,7 +67,7 @@ Run `just --list` to see all available commands. Highlights:
 
 | Command | Description |
 |---------|-------------|
-| `just setup` | Full setup (Python venv + JS deps + dev sidecar). Detects Apple Silicon for MLX and NVIDIA/Intel Arc on Windows for accelerated PyTorch. |
+| `just setup` | Full setup (Python venv + JS deps + dev sidecar). Pins the venv to Python 3.12 (recreating a wrong-version one) and detects Apple Silicon for MLX and NVIDIA/Intel Arc on Windows for accelerated PyTorch. |
 | `just setup-python` | Python venv + dependencies only |
 | `just setup-js` | `bun install` only |
 
@@ -214,8 +216,10 @@ This installs dependencies for:
 ```bash
 cd backend
 
-# Create virtual environment
-python -m venv venv
+# Create virtual environment (use Python 3.12 — see Prerequisites)
+python3.12 -m venv venv   # macOS/Linux
+# or
+py -3.12 -m venv venv     # Windows
 
 # Activate virtual environment
 source venv/bin/activate  # macOS/Linux
@@ -277,7 +281,7 @@ bun run tauri dev
 
 <AccordionGroup>
   <Accordion title="Backend won't start">
-    - Check Python version (must be 3.11+)
+    - Check Python version (must be 3.12)
     - Ensure virtual environment is activated: `source backend/venv/bin/activate`
     - Verify all dependencies are installed: `pip install -r requirements.txt`
     - Check if port 17493 is available

docs/content/docs/overview/troubleshooting.mdx

@@ -292,13 +292,22 @@ This is expected behavior. The first generation downloads the selected TTS engin
 
 <AccordionGroup>
   <Accordion title="Python Version">
-    Ensure Python 3.11 or higher:
+    Ensure Python 3.12:
 
     ```bash
-    python --version
+    python3.12 --version  # macOS/Linux
+    py -3.12 --version    # Windows
     ```
 
-    If not, install Python 3.11+ and recreate the virtual environment.
+    Voicebox pins its venv to Python 3.12 because some dependencies have no 3.13
+    release yet. `just setup` recreates a venv that was built on the wrong version,
+    so re-running it is usually the fix.
+
+    If `just setup` can't find a usable 3.12, install one: `uv python install 3.12`
+    works anywhere; `brew install python@3.12` on macOS; `sudo apt install
+    python3.12 python3.12-venv` on Debian/Ubuntu; or on Windows install from
+    [python.org](https://python.org) / `winget install -e --id Python.Python.3.12`
+    and use the `py -3.12` launcher.
   </Accordion>
 
   <Accordion title="Virtual Environment">