{"id":26963,"library":"esp-idf-nvs-partition-gen","title":"ESP-IDF NVS Partition Generator","description":"Python tool to generate NVS (Non-Volatile Storage) binary partition images for ESP-IDF projects. Extracts configuration from CSV files and produces binary blobs for flash. Current version 0.2.0, maintenance mode on PyPI, released when ESP-IDF requires updates.","status":"maintenance","version":"0.2.0","language":"python","source_language":"en","source_url":"https://github.com/espressif/esp-idf-nvs-partition-gen","tags":["esp32","esp-idf","nvs","partition","csv","embedded"],"install":[{"cmd":"pip install esp-idf-nvs-partition-gen","lang":"bash","label":"PyPI install"}],"dependencies":[],"imports":[{"note":"Exact import path from the package","symbol":"NVSGenerator","correct":"from esp_idf_nvs_partition_gen import NVSGenerator"}],"quickstart":{"code":"from esp_idf_nvs_partition_gen import NVSGenerator\nimport csv\nimport io\n\n# Create a sample CSV in memory\ncsv_data = \"\"\"key,type,encoding,value\nmy_string,namespace,,app\nmy_key,data,string,hello\"\"\"\n\ncsv_file = io.StringIO(csv_data)\nreader = csv.DictReader(csv_file)\n\n# Generate the NVS partition binary\noutput_path = \"partition.bin\"\ngenerator = NVSGenerator(flash_size=0x400000, page_size=0x1000)\ngenerator.add_csv_reader(reader)\ngenerator.generate(output_path)\nprint(f\"Generated NVS partition at {output_path}\")","lang":"python","description":"Generate a binary NVS partition from a CSV. Adjust flash_size and page_size to match your ESP-IDF configuration."},"warnings":[{"fix":"Switch to ESP-IDF's nvs_partition_gen.py tool from the esp-idf repository.","message":"The module 'esp_idf_nvs_partition_gen' is deprecated in favor of ESP-IDF's built-in 'parttool.py' and 'nvs_partition_gen' utility. New projects should use the official ESP-IDF tools.","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Ensure CSV header is: key,type,encoding,value (case-sensitive).","message":"CSV column names must match exactly: 'key','type','encoding','value'. Missing or extra columns cause silent errors or no output.","severity":"gotcha","affected_versions":"all"},{"fix":"For namespace rows, use: key=my_namespace, type=namespace, encoding=<empty>, value=<empty>.","message":"Namespace entries must have 'type' set to 'namespace' and 'encoding' and 'value' left blank. Filling them incorrectly will break the NVS structure.","severity":"gotcha","affected_versions":"all"},{"fix":"Replace: generator.add_csv_file(path) -> reader = csv.DictReader(open(path)); generator.add_csv_reader(reader)","message":"The 'NVSGenerator' class API changed in 0.2.0: 'add_csv_file' method was removed. Use 'add_csv_reader' with a CSV DictReader instead.","severity":"breaking","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'pip install esp-idf-nvs-partition-gen' and use the correct import: 'from esp_idf_nvs_partition_gen import NVSGenerator'.","cause":"Package not installed or wrong import path.","error":"ModuleNotFoundError: No module named 'esp_idf_nvs_partition_gen'"},{"fix":"Use a csv.DictReader object: reader = csv.DictReader(open('file.csv')); generator.add_csv_reader(reader).","cause":"Trying to use the old 'add_csv_file' method with a file path string.","error":"TypeError: add_csv_reader() missing 1 required positional argument: 'reader'"},{"fix":"Ensure 'type' is one of: 'namespace', 'data', 'file'. For string values, use type='data' and encoding='string'.","cause":"CSV 'type' column does not contain a valid ESP-IDF NVS type (e.g., 'data', 'namespace'). Check column content.","error":"ValueError: Invalid entry type: 'string'"},{"fix":"Include all four columns: key,type,encoding,value.","cause":"CSV missing the 'encoding' column header.","error":"KeyError: 'encoding'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}