IPython Deployment and Usage Guide

Prerequisites

Python: Version 3.8 or higher
SQLite3: Required for history functionality (optional if using DummyDB)
Sphinx: For building documentation (if contributing to docs)
Development Tools: Git for cloning the repository

Installation

Clone the Repository

git clone https://github.com/ipython/ipython.git
cd ipython

Install Dependencies

# Install in development mode
pip install -e .

# Or install with optional dependencies
pip install -e ".[all]"

Install IPython Globally

pip install ipython

Install ipdb (Recommended for debugging)

pip install ipdb

Configuration

Global Configuration Files

Pdb Configuration: Create/edit ~/.pdbrc for global pdb settings
IPython Profile: Use ipython profile create to set up a profile

Environment Variables

No specific environment variables are required for basic operation
For custom history storage, configure the history database path

Example Configuration

Create ~/.pdbrc with:

# Skip frames containing __debuggerskip__
skip_predicates debuggerskip false

# Don't hide frames by default
skip_hidden false

# Set context lines
context 25

Build & Run

Running IPython Locally

# Start IPython shell
ipython

# Start with a specific profile
ipython --profile=your_profile

Running with Debugger

# Use ipdb for enhanced debugging
ipython -m ipdb your_script.py

Building Documentation

# Install Sphinx and dependencies
pip install sphinx

# Build documentation
cd docs
make html

Using IPython in Sphinx

Add to your conf.py:

extensions = [
    'IPython.sphinxext.ipython_console_highlighting',
    'IPython.sphinxext.ipython_directive'
]

Deployment

Local Development

IPython is primarily a development tool and doesn't require traditional deployment. For local development:

# Run in development mode
ipython --pdb

Production Usage

For production environments where IPython is used as a dependency:

# Install as a dependency
pip install ipython

Documentation Deployment

If contributing to IPython documentation:

Build documentation locally
Submit changes via pull request
Documentation is automatically deployed to ReadTheDocs

Troubleshooting

Common Issues and Solutions

SQLite3 Not Found

If SQLite3 is not available, IPython will use DummyDB:

# This will silently use DummyDB
import IPython

History Database Issues

# Check if history database exists
ls ~/.ipython/profile_default/history.sqlite

# If corrupted, remove and restart IPython
rm ~/.ipython/profile_default/history.sqlite

Debugger Not Working

Ensure ipdb is installed:

pip install ipdb

Sphinx Directive Issues

If IPython directive doesn't work in Sphinx:

# Check extensions are loaded
extensions = [
    'IPython.sphinxext.ipython_console_highlighting',
    'IPython.sphinxext.ipython_directive'
]

Traceback Formatting Issues

For verbose tracebacks that hang:

# Use non-var version to avoid large data structures
sys.excepthook = ultratb.Verbose_novarsTB()

Frame Skipping Not Working

Check __debuggerskip__ and __tracebackhide__ attributes in your code:

def my_function():
    __debuggerskip__ = True
    # This frame will be skipped

Configuration Not Loading

Verify ~/.pdbrc syntax:

# Check for syntax errors
python -c "import IPython; IPython.core.debugger.Pdb()"

Performance Tips

Use Verbose_novarsTB for large data structures
Configure skip_predicates to improve debugger performance
Use context setting to limit traceback lines displayed

How to Deploy & Use ipython/ipython