A zero-dependency, AI-agent-friendly command-line tool for programmatically editing Jupyter Notebook (.ipynb) files. Designed specifically for Large Language Models (LLMs) and automated workflows.
Traditional Jupyter notebook editing requires either:
- A full Jupyter environment with heavy dependencies
- Manual JSON manipulation (error-prone and fragile)
- Complex libraries that may not work in restricted environments
This tool solves these problems by providing:
✅ Zero Dependencies - Uses only Python standard library
✅ AI-Agent Optimized - Clear CLI interface with file-based I/O pattern
✅ JSON-Safe - Preserves notebook structure and metadata
✅ Portable - Works anywhere Python 3.6+ is installed
✅ Reliable - Predictable behavior for automated workflows
No installation needed! Just download the script:
wget https://raw.githubusercontent.com/yourusername/notebook-editor/main/notebook_editor.py
chmod +x notebook_editor.pyOr clone the repository:
git clone https://github.com/yourusername/notebook-editor.git
cd notebook-editor# List all cells in a notebook
python notebook_editor.py list my_notebook.ipynb
# Read a specific cell
python notebook_editor.py read my_notebook.ipynb 5 --to-file cell_content.py
# Update a cell from file
python notebook_editor.py update my_notebook.ipynb 5 --from-file modified_content.py
# Search for content
python notebook_editor.py search my_notebook.ipynb "import pandas"
# Add a new cell
python notebook_editor.py add my_notebook.ipynb --type code --from-file new_code.py
# Delete a cell
python notebook_editor.py delete my_notebook.ipynb 5Shows all cells with their indices, types, and content preview.
python notebook_editor.py list <notebook.ipynb> [--limit N]Example:
python notebook_editor.py list analysis.ipynb --limit 20Output:
Total cells: 15
[0] CODE: import pandas as pd
[1] CODE: df = pd.read_csv('data.csv')
[2] MARKDOWN: ## Data Analysis
...
Read a specific cell's content to console or file.
python notebook_editor.py read <notebook.ipynb> <cell_index> [--to-file <output_file>]Examples:
# Print to console
python notebook_editor.py read analysis.ipynb 5
# Save to file (RECOMMENDED for code editing)
python notebook_editor.py read analysis.ipynb 5 --to-file cell_5.pySearch for text or regex patterns across all cells.
python notebook_editor.py search <notebook.ipynb> "<query>" [--regex]Examples:
# Simple text search
python notebook_editor.py search analysis.ipynb "import pandas"
# Regex search
python notebook_editor.py search analysis.ipynb "def .*_handler" --regexOutput:
Match in Cell [3] (code):
> import pandas as pd
Match in Cell [7] (code):
> df = pandas.DataFrame()
Found matches in 2 cells: [3, 7]
Replace the content of an existing cell. Automatically clears cell outputs.
python notebook_editor.py update <notebook.ipynb> <cell_index> --from-file <file>
python notebook_editor.py update <notebook.ipynb> <cell_index> --content "<text>"Examples:
# Update from file (RECOMMENDED)
python notebook_editor.py update analysis.ipynb 5 --from-file modified_code.py
# Update with inline text (for simple changes)
python notebook_editor.py update analysis.ipynb 5 --content "print('Hello World')"
# Keep outputs (don't clear)
python notebook_editor.py update analysis.ipynb 5 --from-file code.py --no-clear-outputAdd a new code or markdown cell at a specific position.
python notebook_editor.py add <notebook.ipynb> --type <code|markdown> --from-file <file>
python notebook_editor.py add <notebook.ipynb> --type <code|markdown> --content "<text>"Examples:
# Add at the beginning
python notebook_editor.py add analysis.ipynb --index 0 --type markdown --content "# Introduction"
# Add at the end (default)
python notebook_editor.py add analysis.ipynb --type code --from-file new_analysis.py
# Insert at specific position
python notebook_editor.py add analysis.ipynb --index 5 --type code --content "print('checkpoint')"Delete a cell by its index.
python notebook_editor.py delete <notebook.ipynb> <cell_index>Example:
python notebook_editor.py delete analysis.ipynb 5Show what will change before updating a cell.
python notebook_editor.py diff <notebook.ipynb> <cell_index> --from-file <file>
python notebook_editor.py diff <notebook.ipynb> <cell_index> --content "<text>"Example:
python notebook_editor.py diff analysis.ipynb 5 --from-file modified_code.pyOutput:
--- Cell 5 (Current)
+++ New Content
@@ -1,3 +1,4 @@
import pandas as pd
-df = pd.read_csv('old_data.csv')
+df = pd.read_csv('new_data.csv')
+df = df.dropna()Create a new empty notebook with valid structure.
python notebook_editor.py create <notebook.ipynb>Example:
python notebook_editor.py create new_analysis.ipynbNote for Users: There is a dedicated guide for AI agents located at
README_AGENT.md. Please provide this file to your AI agent to help it understand how to use this tool effectively.
When modifying notebook code, follow this file exchange pattern:
# 1. Explore: Understand the notebook structure
python notebook_editor.py list notebook.ipynb
# 2. Extract: Export cell content to a temporary file
python notebook_editor.py read notebook.ipynb 5 --to-file temp_cell.py
# 3. Edit: Read temp_file.py, make changes, save modifications
# (AI agent or human edits temp_cell.py here)
# 4. Preview: (Optional) Check what will change
python notebook_editor.py diff notebook.ipynb 5 --from-file temp_cell.py
# 5. Apply: Update the cell from the modified file
python notebook_editor.py update notebook.ipynb 5 --from-file temp_cell.py- Reliable: File I/O is more predictable than string manipulation
- Safe: Preview changes before applying them
- Clear: Each step has a single, well-defined purpose
- Debuggable: Intermediate files can be inspected
- LLM-Friendly: Matches how AI agents naturally work with code
- Automated notebook refactoring
- Batch code updates across multiple notebooks
- Programmatic notebook generation
- CI/CD pipeline integration
- Quick notebook editing without Jupyter
- Scripted notebook modifications
- Version control-friendly notebook updates
- Lightweight notebook manipulation in restricted environments
- Python 3.6+ (no external packages required)
- Works on Linux, macOS, and Windows
The tool works with standard Jupyter Notebook format (.ipynb), which is JSON-based:
- Preserves all metadata
- Maintains cell execution counts
- Handles both code and markdown cells
- Supports multi-line content with proper formatting
- Validates JSON structure before saving
- Creates backups implicitly (use version control!)
- Handles edge cases (empty cells, special characters, etc.)
- Provides clear error messages
# Find all cells with old import
python notebook_editor.py search notebook.ipynb "from old_module import"
# For each match, update the cell
python notebook_editor.py read notebook.ipynb 3 --to-file temp.py
# Edit temp.py to replace import
python notebook_editor.py update notebook.ipynb 3 --from-file temp.py# Add markdown cell at the beginning
python notebook_editor.py add notebook.ipynb --index 0 --type markdown --content "# Analysis Report
This notebook performs data analysis on customer data.
## Author: AI Agent
## Date: 2025-11-27"# Search for debug prints
python notebook_editor.py search notebook.ipynb "print.*debug" --regex
# Delete cells with debug code
python notebook_editor.py delete notebook.ipynb 7
python notebook_editor.py delete notebook.ipynb 12Contributions are welcome! This tool is designed to be simple and focused. When contributing:
- Maintain zero-dependency principle
- Keep the CLI interface clean and predictable
- Ensure compatibility with AI agent workflows
- Add tests for new features
MIT License - feel free to use in your projects!
Built for the AI agent community to enable seamless notebook manipulation in automated workflows.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Made with ❤️ for AI Agents and Developers