{"record":{"id":"9b052de1134f6453","repo":"heygen-com/hyperframes","slug":"the-kokoro-onnx-package-is-not-installed-run-pip","errorCode":null,"errorMessage":"The kokoro-onnx package is not installed. Run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)","messagePattern":"The kokoro-onnx package is not installed\\. Run: pip install kokoro-onnx soundfile \\(or point HYPERFRAMES_PYTHON at a venv python that has them\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cli/src/tts/synthesize.ts","lineNumber":140,"sourceCode":"  text: string,\n  outputPath: string,\n  options?: SynthesizeOptions,\n): Promise<SynthesizeResult> {\n  const voice = options?.voice ?? DEFAULT_VOICE;\n  const speed = options?.speed ?? 1.0;\n  const lang: SupportedLang = options?.lang ?? inferLangFromVoiceId(voice);\n\n  // 1. Ensure Python 3 is available with kokoro-onnx\n  options?.onProgress?.(\"Checking Python runtime...\");\n  const python = findPython();\n  if (!python) {\n    throw new Error(\n      \"Python 3 is required for text-to-speech. Install Python 3.10+ and run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)\",\n    );\n  }\n\n  if (!hasPythonPackage(python, \"kokoro_onnx\")) {\n    throw new Error(\n      \"The kokoro-onnx package is not installed. Run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)\",\n    );\n  }\n\n  if (!hasPythonPackage(python, \"soundfile\")) {\n    throw new Error(\"The soundfile package is not installed. Run: pip install soundfile\");\n  }\n\n  // 2. Ensure model and voices are downloaded (parallel on first run)\n  const [modelPath, voicesPath] = await Promise.all([\n    ensureModel(options?.model, { onProgress: options?.onProgress }),\n    ensureVoices({ onProgress: options?.onProgress }),\n  ]);\n\n  // 3. Ensure synthesis script is cached\n  const scriptPath = ensureSynthScript();\n\n  // 4. Ensure output directory exists","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/tts/synthesize.ts#L122-L158","documentation":"Thrown when findPython() succeeds but hasPythonPackage(python, 'kokoro_onnx') returns false. hasPythonPackage actually executes `python -c \"import kokoro_onnx\"` and treats any non-zero exit as missing. This is a genuine import test, not a metadata check, so it also fails when the package is installed but its native deps (onnxruntime, torch) are broken.","triggerScenarios":"Python 3 is present but kokoro-onnx was never pip-installed into that exact interpreter; installed into a different venv than the one on PATH/HYPERFRAMES_PYTHON; installed but import fails due to a missing shared library (libonnxruntime), an incompatible numpy/Python version, or a corrupted install.","commonSituations":"User pip-installed into the system python but HYPERFRAMES_PYTHON points at a venv (or vice versa); a global pip install that landed in a user-site the probed interpreter doesn't read; macOS where brew Python needs `pip install --user`; a torch/onnxruntime ABI mismatch after a Python minor-version upgrade.","solutions":["Install into the SAME interpreter the library probes: `<resolved-python> -m pip install kokoro-onnx soundfile`.","If using a venv, confirm HYPERFRAMES_PYTHON points at its bin/python, not the base interpreter.","Reproduce the import check by hand: `<resolved-python> -c 'import kokoro_onnx'` — if it errors, fix the underlying ImportError it reports.","Reinstall cleanly if the package is present but broken: `pip install --force-reinstall --no-cache-dir kokoro-onnx`.","On Apple Silicon / Linux, ensure onnxruntime's system libs are available (the wheel bundles them, but a stripped container can lose them)."],"exampleFix":"# before: installed into system python, but HYPERFRAMES_PYTHON points elsewhere\npip install kokoro-onnx           # landed in /usr/bin/python3\nexport HYPERFRAMES_PYTHON=/opt/venv/bin/python\n# after: install into the exact interpreter the library uses\n$HYPERFRAMES_PYTHON -m pip install kokoro-onnx soundfile","handlingStrategy":"validation","validationCode":"import { execFileSync } from 'node:child_process';\n\nfunction hasPackage(python: string, pkg: string): boolean {\n  try {\n    execFileSync(python, ['-c', `import ${pkg}`], { stdio: 'pipe', timeout: 10_000 });\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nconst python = process.env.HYPERFRAMES_PYTHON ?? 'python3';\nif (!hasPackage(python, 'kokoro_onnx')) {\n  throw new Error(`Run: ${python} -m pip install kokoro-onnx`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await synthesize(text, out, { voice });\n} catch (err) {\n  if (err instanceof Error && /kokoro-onnx package is not installed/.test(err.message)) {\n    // guide user to install into the exact interpreter\n    console.error(err.message);\n  } else throw err;\n}","preventionTips":["Install kokoro-onnx into the same interpreter HYPERFRAMES_PYTHON points at, not into a global/site-wide python.","Pin kokoro-onnx to a known-good version in a requirements file to avoid surprise upgrades.","After install, verify with `<python> -c 'import kokoro_onnx'` before running the full pipeline."],"tags":["tts","python-runtime","dependency","kokoro","environment"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}