ruvnet/RuView · error · RuntimeError

NVS partition generator not available. Install: pip install

Error message

NVS partition generator not available. Install: pip install esp-idf-nvs-partition-gen

What it means

scripts/generate_nvs_matrix.py builds an NVS partition image for the ESP32 firmware. It tries three strategies in order: `python -m esp_idf_nvs_partition_gen generate`, a direct import of nvs_partition_gen (older API), and the script bundled in ESP-IDF at $IDF_PATH/components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py. This RuntimeError is raised only after all three fail, meaning no NVS generator is reachable from the interpreter running the script.

Source

Thrown at scripts/generate_nvs_matrix.py:332

        idf_path = os.environ.get("IDF_PATH", "")
        gen_script = os.path.join(
            idf_path, "components", "nvs_flash",
            "nvs_partition_generator", "nvs_partition_gen.py"
        )
        if os.path.isfile(gen_script):
            # Fixed interpreter/script plus an argv list (never a shell);
            # csv_path/bin_path are private NamedTemporaryFile paths.
            subprocess.check_call([  # nosemgrep: dangerous-subprocess-use-tainted-env-args
                sys.executable, gen_script, "generate",
                csv_path, bin_path, hex(size)
            ])
            with open(bin_path, "rb") as f:
                return f.read()

        print("ERROR: NVS partition generator tool not found.", file=sys.stderr)
        print("Install: pip install esp-idf-nvs-partition-gen", file=sys.stderr)
        print("Or set IDF_PATH to your ESP-IDF installation", file=sys.stderr)
        raise RuntimeError(
            "NVS partition generator not available. "
            "Install: pip install esp-idf-nvs-partition-gen"
        )

    finally:
        for p in set((csv_path, bin_path)):
            if os.path.isfile(p):
                os.unlink(p)


def main():
    parser = argparse.ArgumentParser(
        description="Generate NVS partition binaries for QEMU firmware test matrix (ADR-061)",
    )
    parser.add_argument(
        "--output-dir", required=True,
        help="Directory to write NVS binary files",
    )

View on GitHub (pinned to 4685618388)

Solutions

Install the generator into the same interpreter: `python -m pip install esp-idf-nvs-partition-gen` (run with the venv active that you use for the script)
Or point at an ESP-IDF checkout: `export IDF_PATH=/path/to/esp-idf` so components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py resolves
Verify the module is reachable: `python -m nvs_partition_gen --help` (or -m esp_idf_nvs_partition_gen) — if that fails, the script will too
In CI, add the pip install step before invoking generate_nvs_matrix.py

Example fix

# before
python scripts/generate_nvs_matrix.py  # RuntimeError: NVS partition generator not available

# after
python -m pip install esp-idf-nvs-partition-gen
python scripts/generate_nvs_matrix.py

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util, os

def nvs_gen_available() -> bool:
    if importlib.util.find_spec("esp_idf_nvs_partition_gen") or importlib.util.find_spec("nvs_partition_gen"):
        return True
    idf = os.environ.get("IDF_PATH", "")
    return os.path.isfile(os.path.join(idf, "components", "nvs_flash", "nvs_partition_generator", "nvs_partition_gen.py"))

Try / catch

try:
    blob = build_nvs_partition(...)  # however you wrap the script
except RuntimeError as e:
    raise SystemExit(f"environment missing NVS tooling: {e}") from e

Prevention

Pin `pip install esp-idf-nvs-partition-gen` in the CI job or requirements before firmware artifact generation
Install the package into the same venv/interpreter that runs the script (the script shells out via sys.executable)
Export IDF_PATH in the environment when relying on an ESP-IDF checkout

When it happens

Trigger: None of: the esp-idf-nvs-partition-gen pip package importable by sys.executable, the legacy nvs_partition_gen module, or a valid IDF_PATH pointing at an ESP-IDF checkout. Note the subprocess calls use sys.executable, so the package must be installed in the same interpreter/venv that runs the script.

Common situations: Fresh CI container without the pip package; the package installed into a different virtualenv than the one running the script; IDF_PATH unset or pointing to an old/moved ESP-IDF directory that lacks the nvs_partition_generator script.

Related errors

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/259ed7d0edbb14d2. Report an issue: GitHub.