{"id":9974,"library":"nbparameterise","title":"nbparameterise Library","description":"nbparameterise is a Python library (current version 0.6.1) designed to re-run Jupyter notebooks while substituting input parameters in the first cell. It's often used for automating notebook execution with different configurations or datasets, making it a valuable tool for reproducible research and data pipeline orchestration. The project maintains a steady release cadence, typically driven by bug fixes and minor feature enhancements.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/takluyver/nbparameterise","tags":["notebooks","jupyter","parameters","workflow","automation","reproducibility"],"install":[{"cmd":"pip install nbparameterise","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for reading and writing Jupyter notebook files.","package":"nbformat","optional":false},{"reason":"Required for actual execution of notebook cells via a Jupyter kernel.","package":"ipykernel","optional":false},{"reason":"A core dependency within the Jupyter ecosystem, used for configuration.","package":"traitlets","optional":false}],"imports":[{"note":"'run_notebook' was an older entry point and has been deprecated/removed in favor of 'parameterise.execute_notebook'.","wrong":"from nbparameterise import run_notebook","symbol":"parameterise","correct":"from nbparameterise import parameterise"},{"note":"'run_notebook_dir' was an older function that has been replaced by 'execute_notebook'.","wrong":"from nbparameterise import run_notebook_dir","symbol":"execute_notebook","correct":"from nbparameterise import execute_notebook"}],"quickstart":{"code":"import os\nfrom nbparameterise import parameterise, execute_notebook\nimport nbformat\n\n# 1. Define the input notebook content (as a string) that includes parameters\ninput_notebook_content = \"\"\"\n{\n \"cells\": [\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": null,\n   \"metadata\": {},\n   \"outputs\": [],\n   \"source\": [\n    \"# Parameters\\n\",\n    \"x = 10\\n\",\n    \"y = 'hello'\"\n   ]\n  },\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": null,\n   \"metadata\": {},\n   \"outputs\": [],\n   \"source\": [\n    \"print(f'Original x: {x}')\\n\",\n    \"print(f'Original y: {y}')\\n\",\n    \"result = x * 2\\n\",\n    \"print(f'Result: {result}')\"\n   ]\n  }\n ],\n \"metadata\": {\n  \"kernelspec\": {\n   \"display_name\": \"Python 3\",\n   \"language\": \"python\",\n   \"name\": \"python3\"\n  },\n  \"language_info\": {\n   \"codemirror_mode\": {\n    \"name\": \"ipython\",\n    \"version\": 3\n   },\n   \"file_extension\": \".py\",\n   \"mimetype\": \"text/x-python\",\n   \"name\": \"python\",\n   \"nbconvert_exporter\": \"python\",\n   \"pygments_lexer\": \"ipython3\",\n   \"version\": \"3.x.x\"\n  }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 4\n}\n\"\"\"\n# Define file paths\ninput_path = \"quickstart_input.ipynb\"\noutput_path = \"quickstart_output.ipynb\"\n\n# Save the dummy input notebook file\nwith open(input_path, \"w\") as f:\n    f.write(input_notebook_content)\nprint(f\"Created input notebook: {input_path}\")\n\ntry:\n    # Load the notebook object\n    with open(input_path) as f:\n        nb = nbformat.read(f, as_version=4)\n\n    # Extract current parameters and define new values to override them\n    params = parameterise.extract_parameters(nb)\n    new_params = parameterise.parameter_values(params, x=25, y=\"world!\") # Override x and y\n    parameterised_nb = parameterise.replace_definitions(nb, new_params)\n\n    # Execute the modified notebook and save the output\n    # Requires 'ipykernel' to be installed in the environment.\n    execute_notebook(parameterised_nb, output_path)\n    print(f\"Notebook executed and saved to {output_path}\")\n\n    # Optionally, verify the output from the executed notebook\n    with open(output_path) as f:\n        output_nb = nbformat.read(f, as_version=4)\n        print(\"\\n--- Output Notebook Cells ---\")\n        for cell in output_nb.cells:\n            if cell.cell_type == 'code':\n                for output in cell.outputs:\n                    if output.output_type == 'stream':\n                        print(output.text.strip())\n\nexcept Exception as e:\n    print(f\"Error during quickstart execution: {e}\")\n    print(\"Hint: Ensure 'ipykernel' is installed (`pip install ipykernel`) for notebook execution.\")\nfinally:\n    # Clean up generated files\n    if os.path.exists(input_path):\n        os.remove(input_path)\n    if os.path.exists(output_path):\n        os.remove(output_path)\n    print(\"\\nCleaned up generated files.\")","lang":"python","description":"This quickstart demonstrates how to programmatically define, parameterise, and execute a Jupyter notebook using `nbparameterise`. It creates a dummy notebook, overrides its initial parameters, executes it, and then prints the output, finally cleaning up generated files. Ensure `ipykernel` is installed for successful execution."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or newer to use nbparameterise versions 0.6.0 and above.","message":"Dropped Python 3.7 support.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Update your code to use `from nbparameterise import parameterise, execute_notebook` and then call `execute_notebook(notebook, path)` instead.","message":"The direct function `run_notebook_dir` was removed and replaced by methods within the `parameterise` object.","severity":"deprecated","affected_versions":"<=0.2.x"},{"fix":"Ensure all variables intended as parameters are assigned in the very first executable code cell. While not strictly required by the library, adding `# Parameters` as a comment in that cell helps for readability and tool recognition.","message":"Parameters are only reliably recognized if defined in the first *code* cell of the notebook.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure 'ipykernel' is installed (`pip install ipykernel`) in the Python environment where `nbparameterise` is being run. If using virtual environments or different kernels, verify the correct kernel is available and registered.","message":"Notebook execution requires an active Jupyter kernel in the environment.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install nbparameterise` to install the package.","cause":"The nbparameterise library is not installed or not available in the current Python environment.","error":"ModuleNotFoundError: No module named 'nbparameterise'"},{"fix":"Verify the path to your input notebook (`your_notebook.ipynb` in the example). Ensure the file exists and the path is absolute, or correct relative to your current working directory.","cause":"The input notebook file path provided to `execute_notebook` does not exist or is incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'your_notebook.ipynb'"},{"fix":"Debug the notebook interactively in a Jupyter environment (e.g., Jupyter Lab or Notebook) to identify the specific cell or error causing the crash. Ensure all dependencies required by the notebook's code are installed and available in the execution environment where `nbparameterise` is run.","cause":"The Jupyter kernel used to execute the notebook crashed. This often indicates an unhandled error within the notebook's code, excessive memory usage, or a missing dependency required by the notebook itself.","error":"NotebookExecutionError: Kernel died during execution."}]}