Installation¶

Get nbctl up and running in minutes!

Requirements¶

Python: 3.8 or higher
Operating Systems: macOS, Linux, Windows
Jupyter: Required (for working with notebooks)

Quick Install¶

Using pip (Recommended)¶

pip install nbctl

Verify Installation¶

# Check version
nbctl --version

# Show help
nbctl --help

Installation Methods¶

1. Install from PyPI (Recommended)¶

For most users, installing from PyPI is the easiest option:

# Basic installation
pip install nbctl

# With development tools
pip install nbctl[dev]

2. Install from Source (Development)¶

For contributors or users who want the latest development version:

# Clone the repository
git clone https://github.com/VenkatachalamSubramanianPeriyaSubbu/nbctl.git
cd nbctl

# Install in editable mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Benefits: - Get the latest features - Make local modifications - Contribute to development

3. Install in Virtual Environment (Recommended)¶

Using a virtual environment keeps your system Python clean:

# Create virtual environment
python -m venv nbctl-env

# Activate on macOS/Linux
source nbctl-env/bin/activate

# Activate on Windows
nbctl-env\Scripts\activate

# Install nbctl
pip install nbctl

# Deactivate when done
deactivate

4. Install with pip User Flag¶

If you don't have admin privileges:

pip install --user nbctl

The command will be installed in your user directory.

Dependencies¶

nbctl automatically installs these dependencies:

Core Dependencies¶

nbformat (≥5.0.0) - Notebook file format
click (≥8.0.0) - CLI framework
rich (≥13.0.0) - Terminal formatting
nbconvert (≥7.0.0) - Notebook conversion
nbclient (≥0.7.0) - Notebook execution
nbdime (≥3.0.0) - Notebook diffing and merging

Development Dependencies (Optional)¶

pytest (≥7.0.0) - Testing framework
pytest-cov (≥4.0.0) - Test coverage
black (≥23.0.0) - Code formatting
mypy (≥1.0.0) - Type checking

To install with development dependencies:

pip install nbctl[dev]

Optional Dependencies¶

For PDF Export¶

PDF export requires LaTeX to be installed on your system:

macOS¶

brew install --cask mactex

Ubuntu/Debian¶

sudo apt-get install texlive-xetex texlive-fonts-recommended texlive-plain-generic

Windows¶

Download and install MiKTeX

Verify LaTeX¶

pdflatex --version

Post-Installation Setup¶

Configure Git Integration (Optional)¶

For optimal notebook version control, set up git integration:

# Run in your git repository
cd your-repo
nbctl git-setup

This configures: - .gitattributes for notebook handling - .gitignore for Python projects - Custom diff driver using nbctl - Custom merge driver using nbctl

Verify Everything Works¶

Test nbctl with a sample notebook:

# Create a test notebook (if you have Jupyter)
jupyter notebook

# Or test with an existing notebook
nbctl info your-notebook.ipynb

# Clean a notebook
nbctl clean your-notebook.ipynb --dry-run

# Get statistics
nbctl info your-notebook.ipynb

Upgrading¶

Upgrade to Latest Version¶

# Upgrade from PyPI
pip install --upgrade nbctl

# Check new version
nbctl --version

Upgrade from Development Branch¶

cd nbctl
git pull origin main
pip install -e .

Uninstalling¶

If you need to uninstall nbctl:

pip uninstall nbctl

To also remove dependencies (if not used by other packages):

pip uninstall nbctl nbformat click rich nbconvert nbclient nbdime

Troubleshooting¶

Command Not Found¶

Problem: nbctl: command not found after installation

Solutions:

Check if installed:
```
pip list | grep nbctl
```
Check Python path:
```
echo $PATH
python -m site --user-base
```
Run with python -m:
```
python -m nbctl.cli --help
```

Add to PATH (macOS/Linux):

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc to make permanent

Permission Errors¶

Problem: Permission denied during installation

Solutions:

Use virtual environment (recommended):

python -m venv venv
source venv/bin/activate
pip install nbctl

Use --user flag:
```
pip install --user nbctl
```
Use sudo (not recommended):
```
sudo pip install nbctl
```

Import Errors¶

Problem: ModuleNotFoundError when running nbctl

Solutions:

Reinstall dependencies:
```
pip install --force-reinstall nbctl
```

Check Python version:

python --version  # Should be 3.8 or higher

Use explicit Python:

python3 -m pip install nbctl
python3 -m nbctl.cli --help

Installation Fails¶

Problem: pip install nbctl fails with errors

Solutions:

Upgrade pip:

pip install --upgrade pip setuptools wheel

Clear pip cache:
```
pip cache purge
pip install nbctl
```

Install from source:

git clone https://github.com/VenkatachalamSubramanianPeriyaSubbu/nbctl.git
cd nbctl
pip install -e .

Platform-Specific Notes¶

macOS¶

Recommended: Use Homebrew to manage Python
M1/M2 Macs: No special configuration needed
Python 2 vs 3: Use python3 and pip3 explicitly

# Install Python via Homebrew
brew install python3

# Install nbctl
pip3 install nbctl

Linux¶

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3-pip
pip3 install nbctl

Fedora/CentOS:

sudo dnf install python3-pip
pip3 install nbctl

Arch:

sudo pacman -S python-pip
pip install nbctl

Windows¶

Recommended: Use Python from python.org
Add Python to PATH during installation
Use Command Prompt or PowerShell

# Install nbctl
pip install nbctl

# If command not found, try:
python -m pip install nbctl
python -m nbctl.cli --help

Docker Installation (Advanced)¶

For containerized environments:

FROM python:3.9-slim

# Install nbctl
RUN pip install nbctl

# Verify installation
RUN nbctl --version

# Set working directory
WORKDIR /notebooks

# Default command
CMD ["nbctl", "--help"]

Build and run:

docker build -t nbctl .
docker run -v $(pwd):/notebooks nbctl clean notebook.ipynb

Next Steps¶

Now that you have nbctl installed:

Learn the basics - Understand what nbctl can do
Explore commands - See all available commands
Try examples - Hands-on learning
Configure git - Set up version control

Getting Help¶

Need help with installation?

Installation complete! Ready to use nbctl? Check out the examples!