NBTemplate

A CLI tool to manage and auto-fill Jupyter Notebook templates - Create reusable notebook templates and quickly generate new notebooks with your custom code blocks.

Features

• Create Templates - Mark code blocks in your notebooks as template placeholders
• Interactive CLI - Get prompted for each template block when creating notebooks
• Easy Distribution - Share templates as .ipynb files
• Flexible Syntax - Use ###TEMPLATE:block_name### or {{block_name}} to mark blocks
• Customizable - Define block descriptions in your templates
• Pre-loaded Templates - Comes with built-in example templates
• Template Management - Organize templates in folders, add new ones easily

Installation

pip install nbtemplate-py

Quick Start

1. See available templates

nbtemplate list

You'll see bundled templates like ml_template that come with the package!

2. Create a notebook from a template

nbtemplate create --output my_notebook.ipynb

The CLI will:

1. Show available templates (bundled + your custom ones)
2. Let you select one
3. Prompt for each template block
4. Create and save your notebook

3. Add your own templates

Create a Jupyter notebook with template markers and save it:

nbtemplate add /path/to/your/template.ipynb

Your custom templates are saved to: ~/.nbtemplate/templates/

Example template structure

Cell 1 - Configuration:

TEMPLATE_CONFIG = {
    "imports": "Import libraries and dependencies",
    "data_loading": "Load and explore your dataset",
    "analysis": "Main analysis code",
    "visualization": "Create plots and visualizations",
}

Cell 2 - Imports Block:

###TEMPLATE:imports###
# Your imports will be inserted here

Cell 3 - Data Loading Block:

###TEMPLATE:data_loading###
# Your data loading code will go here

Cell 4 - Analysis Block:

###TEMPLATE:analysis###
# Your analysis code will go here

Cell 5 - Visualization Block:

###TEMPLATE:visualization###
# Your visualization code will go here

Save as my_template.ipynb and add it:

nbtemplate add my_template.ipynb

Commands

nbtemplate list

List all available templates (bundled + user templates).

nbtemplate list
nbtemplate list --templates-dir ./my_templates

nbtemplate create

Create a new notebook by filling a template interactively.

nbtemplate create
nbtemplate create --output my_notebook.ipynb
nbtemplate create --templates-dir ./my_templates

Options:

• -o, --output: Output notebook path (default: notebook.ipynb)
• --templates-dir: Use a custom templates directory

nbtemplate add

Add a template notebook to your templates directory.

nbtemplate add path/to/template.ipynb
nbtemplate add path/to/template.ipynb --templates-dir ./my_templates

nbtemplate init

Initialize a new templates directory with an example template.

nbtemplate init
nbtemplate init --templates-dir ./my_templates

Template Organization

Bundled Templates

When you install nbtemplate, you get built-in templates:

• ml_template - Machine learning workflow with 6 stages

These are included in the package and work out of the box!

User Templates

Your custom templates are stored in: ~/.nbtemplate/templates/

Just add .ipynb files there and they'll automatically appear in nbtemplate list!

Folder structure:

~/.nbtemplate/
└── templates/
    ├── data_analysis.ipynb
    ├── research_notebook.ipynb
    └── my_custom_template.ipynb

Quick Start

1. Initialize templates directory

nbtemplate init

This creates ~/.nbtemplate/templates/ with an example template.

2. Create your first template

Create a Jupyter notebook with template markers:

# Cell 1 - Configuration
TEMPLATE_CONFIG = {
    "imports": "Import libraries and dependencies",
    "data_loading": "Load and explore your dataset",
    "analysis": "Main analysis code",
    "visualization": "Create plots and visualizations",
}

# Cell 2 - Imports block
###TEMPLATE:imports###
# Your imports will go here

# Cell 3 - Data Loading block
###TEMPLATE:data_loading###
# Your data loading code will go here

# Cell 4 - Analysis block
###TEMPLATE:analysis###
# Your analysis code will go here

# Cell 5 - Visualization block
###TEMPLATE:visualization###
# Your visualization code will go here

Save as my_template.ipynb and add it:

nbtemplate add my_template.ipynb

3. Create notebooks from templates

nbtemplate create

The CLI will:

1. Show available templates
2. Let you select one
3. Prompt for each template block
4. Create and save your notebook

Specify output path:

nbtemplate create --output my_analysis.ipynb

Commands

nbtemplate init

Initialize a new templates directory with an example template.

nbtemplate init
nbtemplate init --templates-dir ./my_templates

nbtemplate list

List all available templates.

nbtemplate list
nbtemplate list --templates-dir ./my_templates

nbtemplate add

Add a template notebook to the templates directory.

nbtemplate add path/to/template.ipynb
nbtemplate add path/to/template.ipynb --templates-dir ./my_templates

nbtemplate create

Create a new notebook by filling a template interactively.

nbtemplate create
nbtemplate create --output my_notebook.ipynb
nbtemplate create --templates-dir ./my_templates

Template Syntax

Mark placeholder blocks in your template using either syntax:

Syntax 1: Comment markers

###TEMPLATE:block_name###
# placeholder code

Syntax 2: Mustache-style

{{block_name}}
# placeholder code

Configuration

Custom templates directory

Set the NBTEMPLATE_DIR environment variable:

# Linux/Mac
export NBTEMPLATE_DIR=/path/to/my/templates
nbtemplate create

# Windows (PowerShell)
$env:NBTEMPLATE_DIR="C:\path\to\templates"
nbtemplate create

Or use --templates-dir with any command:

nbtemplate create --templates-dir /path/to/my/templates

Template block descriptions

Add a TEMPLATE_CONFIG dict in the first code cell to provide descriptions:

TEMPLATE_CONFIG = {
    "imports": "Import necessary libraries",
    "data_loading": "Load and explore data",
    "preprocessing": "Data cleaning and preprocessing",
}

Descriptions are shown when filling templates for context.

Example Workflows

Machine Learning Pipeline

TEMPLATE_CONFIG = {
    'imports': 'Import ML libraries (pandas, scikit-learn, numpy)',
    'data_loading': 'Load and explore your dataset',
    'preprocessing': 'Data preprocessing and feature engineering',
    'model_training': 'Train your machine learning model',
    'evaluation': 'Evaluate model performance with metrics',
    'visualization': 'Create visualizations and plots',
}

Data Analysis

TEMPLATE_CONFIG = {
    "imports": "Import pandas, numpy, matplotlib",
    "data_loading": "Load your CSV or dataset",
    "exploration": "Exploratory data analysis",
    "insights": "Key findings and conclusions",
}

Research Notebook

TEMPLATE_CONFIG = {
    "literature": "Related work and background",
    "hypothesis": "Research hypothesis and approach",
    "implementation": "Implementation of the approach",
    "experiments": "Experimental setup and execution",
    "results": "Results and analysis",
    "conclusion": "Conclusions and future work",
}

Google Colab Support

NBTemplate works great with Google Colab!

# In Colab cell
!pip install nbtemplate
!nbtemplate init
!nbtemplate create --output my_notebook.ipynb

Or download templates from GitHub:

!nbtemplate add https://raw.githubusercontent.com/user/repo/main/templates/ml_template.ipynb
!nbtemplate create

Sharing Templates

Share via GitHub

1. Create a repository for your templates
2. Add your .ipynb template files
3. Share the repository URL
4. Others can clone and add templates

Use Cases

• Data Analysis - Template with data loading, EDA, and visualization blocks
• Machine Learning - Standardized ML pipeline (preprocessing, training, evaluation)
• Reports - Consistent report structure across projects
• Experiments - Reproducible experiment setup
• Education - Structured assignment templates for students
• Team Projects - Standardized notebooks for team collaboration

Python API

You can also use NBTemplate programmatically:

from nbtemplate.template import TemplateManager, TemplateBlockCollector

# Load templates
tm = TemplateManager("~/.nbtemplate/templates")
templates = tm.get_available_templates()

# Fill template
blocks = {
    "imports": "import pandas as pd",
    "data_loading": "df = pd.read_csv('data.csv')",
    "analysis": "print(df.describe())",
}

notebook = tm.fill_template("my_template", blocks)
tm.save_notebook(notebook, "output.ipynb")

Project Structure

nbtemplate/
├── __init__.py          # Package metadata
├── template.py          # Core logic (TemplateManager, TemplateBlockCollector)
├── cli.py              # CLI commands
├── templates/           # Built-in templates
│   ├── ml_template.ipynb   # Example ML template
│   └── __init__.py
├── setup.py            # Package configuration
├── README.md           # This file
└── LICENSE             # MIT License

Troubleshooting

Templates not found

# Check templates directory
nbtemplate list

# Initialize templates
nbtemplate init

# Set custom directory
export NBTEMPLATE_DIR=/your/path
nbtemplate list

Template block not recognized

Check that block markers use the correct syntax:

• ###TEMPLATE:block_name### (triple hashes)
• {{block_name}} (double braces)

Block names must be alphanumeric with underscores.

Requirements

• Python 3.7+
• click (installed automatically)

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Please feel free to:

• Report issues
• Submit pull requests
• Share template ideas
• Suggest improvements

Visit the repository: https://github.com/MakPr016/nbtemplate

Support

For issues, questions, or feature requests, please visit: https://github.com/MakPr016/nbtemplate/issues

---

Made with ❤️ by MakPr016