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

provision.py's generate_nvs_binary() tries three ways to reach the ESP-IDF NVS partition generator: 'python -m esp_idf_nvs_partition_gen', 'python -m nvs_partition_gen', and the bundled script at $IDF_PATH/components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py. If none succeed, it raises RuntimeError instructing you to pip-install the generator. So neither the pip package is importable in the current interpreter nor is IDF_PATH set to a valid ESP-IDF checkout.

Source

Thrown at firmware/esp32-csi-node/provision.py:276

                    return f.read()
            except (subprocess.CalledProcessError, FileNotFoundError):
                continue

        # Method 2: ESP-IDF bundled script
        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()

        raise RuntimeError(
            "NVS partition generator not available. "
            "Install: pip install esp-idf-nvs-partition-gen"
        )

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


def flash_nvs(port, baud, nvs_bin, chip):
    """Flash the NVS partition binary to the ESP32."""
    with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
        f.write(nvs_bin)
        bin_path = f.name

    try:
        cmd = [

View on GitHub (pinned to 4685618388)

Solutions

Install the generator into the interpreter that runs provision.py: 'pip install esp-idf-nvs-partition-gen'.
Alternatively source the ESP-IDF environment so the bundled script is found: '. ~/esp/esp-idf/export.sh' (sets IDF_PATH), then run provision.py in the same shell.
Verify one of the paths works: 'python -m esp_idf_nvs_partition_gen --help' or check that $IDF_PATH/components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py exists.
Confirm you are using the same virtualenv/interpreter used for provisioning (sys.executable is what invokes the module).

Example fix

# before
nvs_bin = generate_nvs_binary(csv_content, 0x6000)  # RuntimeError: NVS partition generator not available

# after
import importlib.util, os, sys
has_pkg = importlib.util.find_spec('esp_idf_nvs_partition_gen') is not None
idf = os.environ.get('IDF_PATH', '')
has_idf = os.path.isfile(os.path.join(idf, 'components', 'nvs_flash',
                                     'nvs_partition_generator', 'nvs_partition_gen.py'))
if not (has_pkg or has_idf):
    raise SystemExit('pip install esp-idf-nvs-partition-gen (or source ESP-IDF export.sh)')
nvs_bin = generate_nvs_binary(csv_content, 0x6000)

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util, os
has_pkg = (importlib.util.find_spec('esp_idf_nvs_partition_gen') is not None
           or importlib.util.find_spec('nvs_partition_gen') is not None)
has_idf = os.path.isfile(os.path.join(
    os.environ.get('IDF_PATH', ''), 'components', 'nvs_flash',
    'nvs_partition_generator', 'nvs_partition_gen.py'))
if not (has_pkg or has_idf):
    raise SystemExit('pip install esp-idf-nvs-partition-gen or source ESP-IDF export.sh')

Prevention

Add esp-idf-nvs-partition-gen to the provisioning requirements/venv so generate_nvs_binary always finds Method 1.
Run provision.py from a shell that sourced ESP-IDF's export.sh when relying on the bundled script (Method 2).
Preflight the environment (find_spec + IDF_PATH check) at the start of provisioning scripts, before any hardware interaction.

When it happens

Trigger: Running 'provision.py' on a machine where the ESP-IDF environment was never sourced (no IDF_PATH) and the esp-idf-nvs-partition-gen package was not pip-installed; running in a venv that lacks the package even though another environment has it; ESP-IDF present but IDF_PATH unset or pointing to a moved/deleted directory.

Common situations: Fresh provisioning workstations; CI containers that install esptool but not the NVS generator; users who sourced export.sh in a different shell than the one running provision.py; IDF_PATH stale after moving the ESP-IDF folder.

Related errors

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