heygen-com/hyperframes · critical

The kokoro-onnx package is not installed. Run: pip install k

Error message

The kokoro-onnx package is not installed. Run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)

What it means

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.

Source

Thrown at packages/cli/src/tts/synthesize.ts:140

  text: string,
  outputPath: string,
  options?: SynthesizeOptions,
): Promise<SynthesizeResult> {
  const voice = options?.voice ?? DEFAULT_VOICE;
  const speed = options?.speed ?? 1.0;
  const lang: SupportedLang = options?.lang ?? inferLangFromVoiceId(voice);

  // 1. Ensure Python 3 is available with kokoro-onnx
  options?.onProgress?.("Checking Python runtime...");
  const python = findPython();
  if (!python) {
    throw new Error(
      "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)",
    );
  }

  if (!hasPythonPackage(python, "kokoro_onnx")) {
    throw new Error(
      "The kokoro-onnx package is not installed. Run: pip install kokoro-onnx soundfile (or point HYPERFRAMES_PYTHON at a venv python that has them)",
    );
  }

  if (!hasPythonPackage(python, "soundfile")) {
    throw new Error("The soundfile package is not installed. Run: pip install soundfile");
  }

  // 2. Ensure model and voices are downloaded (parallel on first run)
  const [modelPath, voicesPath] = await Promise.all([
    ensureModel(options?.model, { onProgress: options?.onProgress }),
    ensureVoices({ onProgress: options?.onProgress }),
  ]);

  // 3. Ensure synthesis script is cached
  const scriptPath = ensureSynthScript();

  // 4. Ensure output directory exists

View on GitHub (pinned to c2996c8626)

Solutions

1. Install into the SAME interpreter the library probes: `<resolved-python> -m pip install kokoro-onnx soundfile`.
2. If using a venv, confirm HYPERFRAMES_PYTHON points at its bin/python, not the base interpreter.
3. Reproduce the import check by hand: `<resolved-python> -c 'import kokoro_onnx'` — if it errors, fix the underlying ImportError it reports.
4. Reinstall cleanly if the package is present but broken: `pip install --force-reinstall --no-cache-dir kokoro-onnx`.
5. On Apple Silicon / Linux, ensure onnxruntime's system libs are available (the wheel bundles them, but a stripped container can lose them).

Example fix

# before: installed into system python, but HYPERFRAMES_PYTHON points elsewhere
pip install kokoro-onnx           # landed in /usr/bin/python3
export HYPERFRAMES_PYTHON=/opt/venv/bin/python
# after: install into the exact interpreter the library uses
$HYPERFRAMES_PYTHON -m pip install kokoro-onnx soundfile

import { execFileSync } from 'node:child_process';

function hasPackage(python: string, pkg: string): boolean {
  try {
    execFileSync(python, ['-c', `import ${pkg}`], { stdio: 'pipe', timeout: 10_000 });
    return true;
  } catch {
    return false;
  }
}

const python = process.env.HYPERFRAMES_PYTHON ?? 'python3';
if (!hasPackage(python, 'kokoro_onnx')) {
  throw new Error(`Run: ${python} -m pip install kokoro-onnx`);
}

try {
  await synthesize(text, out, { voice });
} catch (err) {
  if (err instanceof Error && /kokoro-onnx package is not installed/.test(err.message)) {
    // guide user to install into the exact interpreter
    console.error(err.message);
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Python 3 is required for text-to-speech. Install Python 3.10
• The soundfile package is not installed. Run: pip install sou
• Failed to load @puppeteer/browsers: ${cause} Fix: run `npm i
• Synthesis completed but no output file was created
• Speech was generated but metadata could not be read. Check t

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/9b052de1134f6453. Report an issue: GitHub.