{"id":13468718,"url":"https://github.com/nteract/papermill","last_synced_at":"2025-05-13T11:10:07.664Z","repository":{"id":37335177,"uuid":"96454557","full_name":"nteract/papermill","owner":"nteract","description":"📚 Parameterize, execute, and analyze notebooks","archived":false,"fork":false,"pushed_at":"2025-04-07T20:30:51.000Z","size":1978,"stargazers_count":6156,"open_issues_count":152,"forks_count":438,"subscribers_count":86,"default_branch":"main","last_synced_at":"2025-05-13T11:09:58.301Z","etag":null,"topics":["julia","jupyter","notebook","notebook-generator","notebooks","nteract","pipeline","publishing","python","r","scala"],"latest_commit_sha":null,"homepage":"http://papermill.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nteract.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-07-06T17:17:53.000Z","updated_at":"2025-05-11T11:51:44.000Z","dependencies_parsed_at":"2023-10-10T17:53:56.014Z","dependency_job_id":"3efe85fb-f80d-4b36-9b14-74a0a667af25","html_url":"https://github.com/nteract/papermill","commit_stats":{"total_commits":793,"total_committers":127,"mean_commits":6.244094488188976,"dds":0.7023959646910467,"last_synced_commit":"0ee530d11b5d20c7fb8604bd021558970e369b64"},"previous_names":[],"tags_count":79,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fpapermill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fpapermill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fpapermill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nteract%2Fpapermill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nteract","download_url":"https://codeload.github.com/nteract/papermill/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253929367,"owners_count":21985802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["julia","jupyter","notebook","notebook-generator","notebooks","nteract","pipeline","publishing","python","r","scala"],"created_at":"2024-07-31T15:01:17.394Z","updated_at":"2025-05-13T11:10:07.517Z","avatar_url":"https://github.com/nteract.png","language":"Python","funding_links":[],"categories":["Python","Documentation and Presentation","Data Science Notebook Frameworks","scala","Rendering/Publishing/Conversion","julia","交互式小部件和可视化","Data Science Notebook","Interactive Widgets \u0026 Visualization","Notebooks (Python)","📦 Additional Python Libraries"],"sub_categories":["Miscellaneous"],"readme":"# \u003ca href=\"https://github.com/nteract/papermill\"\u003e\u003cimg src=\"https://media.githubusercontent.com/media/nteract/logos/master/nteract_papermill/exports/images/png/papermill_logo_wide.png\" height=\"48px\" /\u003e\u003c/a\u003e\n\n\u003c!---(binder links generated at https://mybinder.readthedocs.io/en/latest/howto/badges.html and compressed at https://tinyurl.com) --\u003e\n\n[![CI](https://github.com/nteract/papermill/actions/workflows/ci.yml/badge.svg)](https://github.com/nteract/papermill/actions/workflows/ci.yml)\n[![CI](https://github.com/nteract/papermill/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/nteract/papermill/actions/workflows/ci.yml)\n[![image](https://codecov.io/github/nteract/papermill/coverage.svg?branch=main)](https://codecov.io/github/nteract/papermill?branch=main)\n[![Documentation Status](https://readthedocs.org/projects/papermill/badge/?version=latest)](http://papermill.readthedocs.io/en/latest/?badge=latest)\n[![badge](https://tinyurl.com/ybwovtw2)](https://mybinder.org/v2/gh/nteract/papermill/main?filepath=binder%2Fprocess_highlight_dates.ipynb)\n[![badge](https://tinyurl.com/y7uz2eh9)](https://mybinder.org/v2/gh/nteract/papermill/main?)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/papermill)](https://pypi.org/project/papermill/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n[![papermill](https://snyk.io/advisor/python/papermill/badge.svg)](https://snyk.io/advisor/python/papermill)\n[![Anaconda-Server Badge](https://anaconda.org/conda-forge/papermill/badges/downloads.svg)](https://anaconda.org/conda-forge/papermill)\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/nteract/papermill/main.svg)](https://results.pre-commit.ci/latest/github/nteract/papermill/main)\n\n**papermill** is a tool for parameterizing, executing, and analyzing\nJupyter Notebooks.\n\nPapermill lets you:\n\n- **parameterize** notebooks\n- **execute** notebooks\n\nThis opens up new opportunities for how notebooks can be used. For\nexample:\n\n- Perhaps you have a financial report that you wish to run with\n  different values on the first or last day of a month or at the\n  beginning or end of the year, **using parameters** makes this task\n  easier.\n- Do you want to run a notebook and depending on its results, choose a\n  particular notebook to run next? You can now programmatically\n  **execute a workflow** without having to copy and paste from\n  notebook to notebook manually.\n\nPapermill takes an *opinionated* approach to notebook parameterization and\nexecution based on our experiences using notebooks at scale in data\npipelines.\n\n## Installation\n\nFrom the command line:\n\n```{.sourceCode .bash}\npip install papermill\n```\n\nFor all optional io dependencies, you can specify individual bundles\nlike `s3`, or `azure` -- or use `all`. To use Black to format parameters you can add as an extra requires \\['black'\\].\n\n```{.sourceCode .bash}\npip install papermill[all]\n```\n\n## Python Version Support\n\nThis library currently supports Python 3.8+ versions. As minor Python\nversions are officially sunset by the Python org papermill will similarly\ndrop support in the future.\n\n## Usage\n\n### Parameterizing a Notebook\n\nTo parameterize your notebook designate a cell with the tag `parameters`.\n\n![enable parameters in Jupyter](docs/img/enable_parameters.gif)\n\nPapermill looks for the `parameters` cell and treats this cell as defaults for the parameters passed in at execution time. Papermill will add a new cell tagged with `injected-parameters` with input parameters in order to overwrite the values in `parameters`. If no cell is tagged with `parameters` the injected cell will be inserted at the top of the notebook.\n\nAdditionally, if you rerun notebooks through papermill and it will reuse the `injected-parameters` cell from the prior run. In this case Papermill will replace the old `injected-parameters` cell with the new run's inputs.\n\n![image](docs/img/parameters.png)\n\n### Executing a Notebook\n\nThe two ways to execute the notebook with parameters are: (1) through\nthe Python API and (2) through the command line interface.\n\n#### Execute via the Python API\n\n```{.sourceCode .python}\nimport papermill as pm\n\npm.execute_notebook(\n   'path/to/input.ipynb',\n   'path/to/output.ipynb',\n   parameters = dict(alpha=0.6, ratio=0.1)\n)\n```\n\n#### Execute via CLI\n\nHere's an example of a local notebook being executed and output to an\nAmazon S3 account:\n\n```{.sourceCode .bash}\n$ papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1\n```\n\n**NOTE:**\nIf you use multiple AWS accounts, and you have [properly configured your AWS  credentials](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html), then you can specify which account to use by setting the `AWS_PROFILE` environment variable at the command-line. For example:\n\n```{.sourceCode .bash}\n$ AWS_PROFILE=dev_account papermill local/input.ipynb s3://bkt/output.ipynb -p alpha 0.6 -p l1_ratio 0.1\n```\n\nIn the above example, two parameters are set: `alpha` and `l1_ratio` using `-p` (`--parameters` also works). Parameter values that look like booleans or numbers will be interpreted as such. Here are the different ways users may set parameters:\n\n```{.sourceCode .bash}\n$ papermill local/input.ipynb s3://bkt/output.ipynb -r version 1.0\n```\n\nUsing `-r` or `--parameters_raw`, users can set parameters one by one. However, unlike `-p`, the parameter will remain a string, even if it may be interpreted as a number or boolean.\n\n```{.sourceCode .bash}\n$ papermill local/input.ipynb s3://bkt/output.ipynb -f parameters.yaml\n```\n\nUsing `-f` or `--parameters_file`, users can provide a YAML file from which parameter values should be read.\n\n```{.sourceCode .bash}\n$ papermill local/input.ipynb s3://bkt/output.ipynb -y \"\nalpha: 0.6\nl1_ratio: 0.1\"\n```\n\nUsing `-y` or `--parameters_yaml`, users can directly provide a YAML string containing parameter values.\n\n```{.sourceCode .bash}\n$ papermill local/input.ipynb s3://bkt/output.ipynb -b YWxwaGE6IDAuNgpsMV9yYXRpbzogMC4xCg==\n```\n\nUsing `-b` or `--parameters_base64`, users can provide a YAML string, base64-encoded, containing parameter values.\n\nWhen using YAML to pass arguments, through `-y`, `-b` or `-f`, parameter values can be arrays or dictionaries:\n\n```{.sourceCode .bash}\n$ papermill local/input.ipynb s3://bkt/output.ipynb -y \"\nx:\n    - 0.0\n    - 1.0\n    - 2.0\n    - 3.0\nlinear_function:\n    slope: 3.0\n    intercept: 1.0\"\n```\n\n#### Supported Name Handlers\n\nPapermill supports the following name handlers for input and output paths during execution:\n\n- Local file system: `local`\n\n- HTTP, HTTPS protocol:  `http://, https://`\n\n- Amazon Web Services: [AWS S3](https://aws.amazon.com/s3/) `s3://`\n\n- Azure: [Azure DataLake Store](https://docs.microsoft.com/en-us/azure/data-lake-store/data-lake-store-overview), [Azure Blob Store](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-overview) `adl://, abs://`\n\n- Google Cloud: [Google Cloud Storage](https://cloud.google.com/storage/) `gs://`\n\n## Development Guide\n\nRead [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to setup a local development environment and make code changes back to Papermill.\n\nFor development guidelines look in the [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md) file. This should inform you on how to make particular additions to the code base.\n\n## Documentation\n\nWe host the [Papermill documentation](http://papermill.readthedocs.io)\non ReadTheDocs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnteract%2Fpapermill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnteract%2Fpapermill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnteract%2Fpapermill/lists"}