Jupyter Notebook to Python Script Converter

Convert .ipynb notebooks to clean .py scripts with nbconvert, jupytext, and papermill — with CI/CD integration and best practices.

Why Convert Notebooks to Scripts?

Jupyter notebooks are indispensable for exploratory data analysis and rapid prototyping, but they come with real friction in production workflows. Version control diffs are noisy JSON blobs, notebooks can't be imported as modules, and CI/CD pipelines expect plain Python files. Converting .ipynb files to .py scripts unlocks cleaner Git history, standard linting tools, automated testing with pytest, and straightforward deployment to production systems.

The Python ecosystem offers three distinct tools for this — each solving a different part of the problem. nbconvert is the standard one-way exporter. Jupytext maintains bidirectional sync between notebook and script formats. Papermill executes parameterized notebooks without converting them at all. Understanding which tool fits your workflow is the first step.

nbconvert: The Standard CLI Converter

nbconvert ships with JupyterLab and is the go-to tool for one-time or scripted conversions. It supports multiple output formats including Python scripts, HTML, LaTeX, PDF, Markdown, and RST. For script conversion, markdown cells become Python comments and code cells are preserved as-is.

# Basic conversion
jupyter nbconvert --to script analysis.ipynb

# Convert all notebooks in a directory
jupyter nbconvert --to script notebooks/*.ipynb

# Convert and execute before exporting
jupyter nbconvert --to script --execute analysis.ipynb

# Strip outputs first, then convert
pip install nbstripout
nbstripout analysis.ipynb
jupyter nbconvert --to script analysis.ipynb

# Export only code (no markdown as comments)
jupyter nbconvert --to script --no-prompt analysis.ipynb

Key flags to know:

• --to script — output format (also: html, pdf, markdown, rst)
• --execute — run the notebook before exporting
• --output-dir — specify a different output directory
• --no-prompt — omit In[N] / Out[N] prompts
• --TagRemovePreprocessor.enabled=True — filter cells by tag

Papermill: Parameterized Notebook Execution

Papermill takes a different approach — instead of converting notebooks to scripts, it runs them with injected parameters and saves the executed output as a new notebook. This is ideal for scheduled reports, batch processing jobs, and model retraining pipelines where you want to preserve the rich output (plots, DataFrames, logs) alongside the code.

Tag a cell with parameters in Jupyter's cell metadata to mark it as the injection point. Papermill replaces that cell's values at runtime.

# Install papermill
pip install papermill

# Run notebook with parameters
papermill input_notebook.ipynb output_notebook.ipynb \
  -p alpha 0.05 \
  -p data_path /data/train.csv \
  -p n_estimators 200

# Run from Python
import papermill as pm

pm.execute_notebook(
   'analysis_template.ipynb',
   'analysis_output_2026-04-02.ipynb',
   parameters=dict(
       alpha=0.05,
       data_path='/data/train.csv',
       n_estimators=200
   )
)

Papermill integrates naturally with Airflow, Prefect, and Luigi. Each DAG task can execute a notebook with different parameters, and the output notebooks serve as self-documenting execution logs — far richer than plain text logs.

Jupytext: Bidirectional Sync for Teams

Jupytext solves the version control problem by pairing every notebook with a lightweight text representation (.py, .md, or .R). When you edit either file, Jupytext synchronizes the changes to the other. Your Git diffs become readable Python code, code review in GitHub PRs becomes possible, and any developer can work in their preferred editor without losing notebook functionality.

# Install jupytext
pip install jupytext

# Pair an existing notebook with a .py file
jupytext --set-formats ipynb,py:percent analysis.ipynb

# Sync changes from .py back to .ipynb
jupytext --sync analysis.py

# Convert .py to .ipynb
jupytext --to notebook analysis.py

# Auto-pair all new notebooks (add to jupyter_notebook_config.py)
# c.ContentsManager.default_jupytext_formats = "ipynb,py:percent"

# The percent format looks like this in .py:
# %% [markdown]
# # Section Title

# %%
import pandas as pd
df = pd.read_csv('data.csv')

The percent format is the most popular — cells are delimited by # %% markers, which VS Code, Spyder, and PyCharm all recognize natively. The light format is even cleaner but less compatible with editors.

CI/CD Integration

A robust notebook CI/CD pipeline typically combines nbstripout (to strip outputs before commit), nbconvert (to generate testable scripts), and pytest (to validate the generated code). Here is a complete GitHub Actions workflow:

# .github/workflows/notebook-tests.yml
name: Notebook Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install jupyter nbconvert nbstripout pytest

      - name: Strip outputs
        run: nbstripout notebooks/*.ipynb

      - name: Convert notebooks to scripts
        run: jupyter nbconvert --to script notebooks/*.ipynb --output-dir=tests/

      - name: Run tests
        run: pytest tests/ -v

For pre-commit hooks, add nbstripout to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/kynan/nbstripout
    rev: 0.6.1
    hooks:
      - id: nbstripout

Best Practices for Production Notebook Workflows

• Separate exploration from production: Keep exploratory notebooks in a notebooks/ folder and auto-generate scripts to src/ for import and testing.
• Always strip outputs before committing: Use nbstripout as a pre-commit hook to keep repository size manageable and diffs meaningful.
• Use cell tags consistently: Tag cells as parameters, imports, visualization, or exclude to enable selective export and papermill parameterization.
• Test generated scripts in CI: Convert notebooks and run basic smoke tests (import, shape checks, output type checks) in every pull request.
• Pin nbconvert version: Conversion behavior can change between versions. Pin to a specific version in requirements-dev.txt to ensure reproducible builds.
• Consider Quarto for documentation: If your notebooks produce reports, Quarto extends the nbconvert concept with richer templating and multi-format publishing.

Choosing the Right Tool

Use nbconvert when you need a one-off or scripted export and don't need the scripts to stay in sync with the notebook. Use jupytext when your team works across notebooks and editors and you want clean Git history. Use papermill when you want to run notebooks as scheduled jobs with varying parameters and need execution records. Many mature data science teams use all three in combination — jupytext for development, nbconvert for CI tests, and papermill for production scheduling.