{"id":1615,"library":"papermill","title":"Papermill","description":"Papermill is a Python library that allows you to parameterize and execute Jupyter and nteract Notebooks. It's widely used for creating dynamic reports, running ETL jobs, and orchestrating data science workflows where notebook execution is a core component. The current version is 2.7.0, and it generally follows a release cadence tied to new features or critical bug fixes.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/nteract/papermill/","tags":["notebooks","jupyter","automation","etl","parameterization","data-science"],"install":[{"cmd":"pip install papermill","lang":"bash","label":"Standard Install"}],"dependencies":[{"reason":"Required to execute notebooks within environments where the default 'python3' kernel might not be sufficient or correctly configured. Papermill orchestrates, but a kernel performs the cell execution.","package":"ipykernel","optional":true}],"imports":[{"note":"While direct import works, aliasing to 'pm' is conventional and avoids name conflicts, especially when using other functions from the library.","wrong":"from papermill import execute_notebook","symbol":"execute_notebook","correct":"import papermill as pm\npm.execute_notebook(...)"}],"quickstart":{"code":"import papermill as pm\nimport os\n\n# Create a dummy input notebook file for demonstration\nnotebook_content = '''\n{\n \"cells\": [\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": null,\n   \"metadata\": {\"tags\": [\"parameters\"]},\n   \"outputs\": [],\n   \"source\": [\"# Parameters injected here\"] \\\n      + [\"message = 'default'\"],\n   \"user_expression\": []\n  },\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": null,\n   \"metadata\": {},\n   \"outputs\": [],\n   \"source\": [\"print(f'Hello from Papermill: {message}')\"],\n   \"user_expression\": []\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.9.7\" # Placeholder, will use current env's python\n  }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 5\n}\n'''\n\nwith open('input_notebook.ipynb', 'w') as f:\n    f.write(notebook_content.replace('3.9.7', f'{os.sys.version_info.major}.{os.sys.version_info.minor}.{os.sys.version_info.micro}'))\n\n\ninput_path = 'input_notebook.ipynb'\noutput_path = 'output_notebook.ipynb'\nparameters = {'message': 'Papermill is awesome!'}\n\ntry:\n    # Execute the notebook with parameters\n    pm.execute_notebook(\n        input_path,\n        output_path,\n        parameters=parameters,\n        report_mode=True # Saves additional metadata for reporting\n    )\n    print(f\"Notebook executed successfully. Output saved to {output_path}\")\n\n    # Optionally read the output notebook to verify content\n    # import nbformat\n    # with open(output_path, 'r') as f:\n    #     nb = nbformat.read(f, as_version=4)\n    #     print(\"\\nOutput Notebook Content (first few lines):\\n\")\n    #     for cell in nb.cells:\n    #         if cell.cell_type == 'code' and cell.outputs:\n    #             for output in cell.outputs:\n    #                 if 'text' in output.data:\n    #                     print(output.data['text']['plain'])\n\nexcept pm.exceptions.PapermillExecutionError as e:\n    print(f\"Papermill execution failed: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Clean up dummy files\n    if os.path.exists('input_notebook.ipynb'):\n        os.remove('input_notebook.ipynb')\n    if os.path.exists('output_notebook.ipynb'):\n        os.remove('output_notebook.ipynb')","lang":"python","description":"This quickstart demonstrates how to use `papermill.execute_notebook` to run a Jupyter notebook with injected parameters. It creates a simple input notebook on the fly, executes it, and saves the output. The `parameters` dictionary is used to override variables defined in cells tagged with 'parameters' in the input notebook. Error handling is included for robust execution."},"warnings":[{"fix":"Refer to the Papermill 2.0 migration guide for detailed changes. Update function calls and parameter names as needed. Replace `pm.view` functionality with direct notebook inspection or alternative display methods.","message":"Papermill 2.0.0 introduced significant breaking changes, including the removal of `pm.view` and modifications to argument names/defaults in `execute_notebook`. Code written for Papermill 1.x will likely require updates.","severity":"breaking","affected_versions":"2.0.0 and above"},{"fix":"Before executing, verify the target kernel environment (e.g., a specific Conda env or virtualenv) has all dependencies required by the notebook. You can use `pip install -t /path/to/kernel/env-site-packages your-package` or activate the environment before installing.","message":"The environment where Papermill is run is separate from the kernel environment used by the executed notebook. Ensure the kernel specified in your notebook (e.g., 'python3') has all necessary libraries installed, not just the environment where Papermill itself is installed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To catch notebook-level errors, set `raise_on_error=True` in `execute_notebook`. Alternatively, after execution, programmatically inspect the output notebook for error messages in cell outputs or check the exit code if running via the CLI. For a softer approach, `report_mode=True` adds helpful metadata.","message":"A `papermill.execute_notebook` call might complete successfully even if the underlying notebook cells raise errors. Papermill records the errors within the output notebook but doesn't necessarily propagate them as an exception by default.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is 3.10 or newer. If you need to use an older Python version, you must downgrade Papermill to a compatible 1.x release, which is not recommended for new projects due to lack of active maintenance.","message":"Papermill 2.x, including the current 2.7.0, requires Python >=3.10. Older versions of Papermill supported earlier Python versions (e.g., 3.6+).","severity":"breaking","affected_versions":"2.0.0 and above"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}