VoiceForge needs Python 3.11 or 3.12 on your Mac for development, Mac-native MPS workers, and smoke tests. Docker remains the simplest CPU API/UI profile, but Linux containers on Docker Desktop cannot use Apple Metal.
If python or pip show as “command not found”, use this guide.
Open Terminal (or Cursor’s terminal) and run:
echo "$SHELL"
echo "$PATH" | tr ':' '\n' | head -20
which python3 python pip3 pip 2>&1
python3 --version 2>&1
/usr/local/bin/python3 --version 2>&1| Result | Meaning |
|---|---|
python3 works, python does not |
Normal on Homebrew macOS — use python3 / pip3, or add aliases below |
python3 not found |
Homebrew Python not on PATH — fix PATH (below) or reinstall |
Only works inside this repo after source .venv/bin/activate |
Global PATH broken; venv is fine for this project only |
A common mistake is replacing PATH in ~/.zshrc with a hard-coded list.
That drops Homebrew paths and breaks python3.
Correct pattern (append tool dirs to the existing system PATH):
# ~/.zshrc — append only
export PATH="/usr/local/bin:/usr/local/sbin:$PATH"
export PATH="/usr/local/opt/python@3.12/bin:$PATH"Wrong pattern (avoid):
export PATH="/usr/local/bin:/usr/bin:/bin" # replaces everything elseAfter editing ~/.zshrc:
source ~/.zshrc
which python3
python3 --versionThis repo’s maintainer setup uses Homebrew Python 3.12 at
/usr/local/opt/python@3.12/bin/python3.12.
Homebrew often installs python3 only, not python.
Options:
A. Use explicit names (recommended)
python3 --version
pip3 --versionB. Aliases in ~/.zshrc
alias python=python3
alias pip='python3 -m pip'Then: source ~/.zshrc
If /usr/local/bin/python3 does not exist:
brew install python@3.12
brew link python@3.12
echo 'export PATH="/usr/local/opt/python@3.12/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
python3.12 --versionDo not remove system /usr/bin/python3 (Apple stub); use Homebrew’s
python3.12 for development.
From the repo root (after python3 works):
cd /path/to/audio-cloning
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e ".[dev]"
pytest -qInside an activated venv, python and pip work without global aliases.
Homebrew Python 3.13+ blocks pip install outside a venv:
error: externally-managed-environment
Do not use --break-system-packages — it can break Homebrew Python and
weakens isolation.
A. Project venv (recommended for VoiceForge)
cd /path/to/audio-cloning
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -e ".[dev]"B. pipx (optional CLI tools only, separate venv per tool)
brew install pipx
pipx ensurepath
source ~/.zshrc # adds ~/.local/binC. Never do this
Do not use pip install --break-system-packages ....
VoiceForge includes pip-audit in the dev extra. Run inside the project venv:
source .venv/bin/activate
pip install -e ".[dev]"
pip-auditFix reported issues by upgrading pinned deps in requirements*.txt /
pyproject.toml, then re-run tests. Do not install random packages into
system Python.
| Issue | Fix |
|---|---|
python: command not found but python3 works |
Use python3.12 or add aliases (Fix 2) |
PATH missing /usr/local/bin |
Append in ~/.zshrc (Fix 1); never replace entire PATH |
externally-managed-environment on pip install |
Use venv or pipx (Fix 4); never --break-system-packages |
Default python3 is 3.13 |
Prefer python3.12 for this project (see aliases in ~/.zshrc) |
Documents/software/gradle/bin in PATH without $HOME |
Use $HOME/Documents/software/gradle/bin |
Duplicate .venv/bin repeated in PATH |
Remove duplicate source .venv/bin/activate from shell startup |
| Cursor terminal differs from Terminal.app | Both read ~/.zshrc for zsh; run echo $SHELL to confirm |