Complete setup guide for runcell - Direct installation, virtual environments, and Docker setups

Setup Guide

This guide covers different ways to set up runcell in your development environment. Choose the method that best fits your workflow and requirements.

Prerequisites

Before starting with any setup method, ensure you have:

Python 3.10 or higher
JupyterLab 4.0 or higher (Jupyter Notebook is not supported)
Internet connection for installation

Direct Installation

Method 1: pip (Recommended)

The simplest way to install runcell:

pip install runcell

Start JupyterLab:

jupyter lab

Method 2: conda

If you're using conda environments:

# Activate your conda environment
conda activate your-environment-name

# Install runcell (using pip within conda)
pip install runcell

# Start JupyterLab
jupyter lab

Method 3: uv (Ultra-fast)

For the fastest installation experience:

# Install uv if you don't have it
pip install uv

# Install runcell with uv
uv pip install runcell

# Start JupyterLab
jupyter lab

Virtual Environment Setup

Quick venv Setup

This is the recommended approach for isolated development environments:

Step 1: Create and Activate Virtual Environment

# Create a new virtual environment
python -m venv runcell-env

# Activate the environment
# On macOS/Linux:
source runcell-env/bin/activate
# On Windows:
# runcell-env\Scripts\activate

Step 2: Upgrade pip and Install Dependencies

# Upgrade pip to latest version
pip install --upgrade pip

# Install JupyterLab first
pip install jupyterlab

# Install runcell
pip install runcell

Step 3: Verify Installation

# Check versions
python --version  # Should be 3.10+
jupyter lab --version  # Should be 4.0+

Step 4: Start JupyterLab

jupyter lab

Advanced venv Setup with Development Tools

For a more complete development environment:

# Create and activate virtual environment
python -m venv runcell-dev-env
source runcell-dev-env/bin/activate  # macOS/Linux
# runcell-dev-env\Scripts\activate  # Windows

# Install development dependencies
pip install --upgrade pip
pip install jupyterlab ipykernel ipywidgets
pip install runcell

# Register the kernel with Jupyter
python -m ipykernel install --user --name=runcell-dev-env

# Start JupyterLab
jupyter lab

Conda Virtual Environment

# Create a new conda environment
conda create -n runcell-env python=3.11 jupyterlab

# Activate the environment
conda activate runcell-env

# Install runcell with pip (recommended)
pip install runcell

# Start JupyterLab
jupyter lab

Docker Setup

Using jupyter/pyspark-notebook

This setup provides a complete Jupyter environment with PySpark and runcell in a containerized environment.

Step 1: Create Dockerfile

Create a Dockerfile in your project directory:

# Use the official Jupyter PySpark notebook as base
FROM quay.io/jupyter/pyspark-notebook:latest

# Switch to root to install system packages
USER root

# Update system packages
RUN apt-get update && apt-get install -y \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Switch back to jovyan user
USER $NB_UID

# Install runcell and upgrade JupyterLab
RUN pip install --no-cache-dir \
    jupyterlab>=4.0 \
    runcell

# Expose JupyterLab port
EXPOSE 8888

# Start JupyterLab
CMD ["start-notebook.sh", "--LabApp.ip=0.0.0.0", "--LabApp.port=8888", "--LabApp.allow_root=True", "--LabApp.token=''"]

Step 2: Build and Run

# Build the Docker image
docker build -t runcell-jupyter .

# Run the container
docker run -p 8888:8888 -v $(pwd):/home/jovyan/work runcell-jupyter

Step 3: Access JupyterLab

Open your browser and navigate to: http://localhost:8888

Docker Compose Setup

For a more robust setup, create a docker-compose.yml:

version: '3.8'

services:
  jupyter:
    build: .
    ports:
      - "8888:8888"
    volumes:
      - ./notebooks:/home/jovyan/work
      - jupyter_data:/home/jovyan/.jupyter
    environment:
      - JUPYTER_ENABLE_LAB=yes
      - JUPYTER_TOKEN=your-secure-token-here
    restart: unless-stopped

volumes:
  jupyter_data:

Run with:

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Minimal Docker Setup

For a lightweight setup without PySpark:

FROM jupyter/base-notebook:latest

USER root

# Install system dependencies if needed
RUN apt-get update && apt-get install -y \
    && rm -rf /var/lib/apt/lists/*

USER $NB_UID

# Install JupyterLab and runcell
RUN pip install --no-cache-dir \
    jupyterlab>=4.0 \
    runcell

EXPOSE 8888

CMD ["start-notebook.sh", "--LabApp.ip=0.0.0.0", "--LabApp.port=8888"]

Verification Steps

After completing any setup method, verify your installation:

1. Check Versions

python --version     # Should show 3.10+
jupyter lab --version  # Should show 4.0+

2. Start JupyterLab

jupyter lab

3. Find runcell Extension

Look for the runcell extension in the right sidebar
Click on the runcell icon to activate
Follow any setup prompts

4. Test Basic Functionality

Create a new notebook and test if runcell features are available.

Troubleshooting

Common Issues

Extension Not Visible

Restart JupyterLab completely
Clear browser cache
Verify JupyterLab version is 4.0+

Python Version Issues

# Check Python version
python --version

# If using pyenv, install newer Python
pyenv install 3.11
pyenv global 3.11

Permission Errors

# Install with user flag
pip install --user runcell

# Or fix permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.local/

Docker Issues

# Pull latest base image
docker pull quay.io/jupyter/pyspark-notebook:latest

# Clean build
docker build --no-cache -t runcell-jupyter .

# Check container logs
docker logs <container-id>

Environment-Specific Solutions

macOS

# If using Homebrew Python
brew install python@3.11
pip3.11 install runcell jupyterlab

Ubuntu/Debian

# Install Python 3.11
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-pip
python3.11 -m pip install runcell jupyterlab

Windows

# Using Windows Package Manager
winget install Python.Python.3.11
pip install runcell jupyterlab

Next Steps

Once runcell is installed and working:

Explore Features: Check out the runcell extension in JupyterLab's right sidebar
Create Notebooks: Start experimenting with enhanced cell execution
Read Documentation: Learn about advanced runcell capabilities
Join Community: Connect with other runcell users

Support

If you encounter issues during setup:

Check the troubleshooting section above
Verify all prerequisites are met
Try a clean installation in a new environment
Check JupyterLab logs for error messages

Choose the setup method that best fits your workflow and start enhancing your Jupyter notebook experience with runcell!

Setup Guide

On this page