# Setup Guide

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

Canonical HTML: https://www.runcell.dev/docs/setup

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.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:

```bash
pip install runcell
```

Start JupyterLab:

```bash
jupyter lab
```

### Method 2: conda

If you're using conda environments:

```bash
# 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:

```bash
# 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

```bash
# 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

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

# Install JupyterLab first
pip install jupyterlab

# Install runcell
pip install runcell
```

#### Step 3: Verify Installation

```bash
# Check versions
python --version  # Should be 3.10+
jupyter lab --version  # Should be 4.4.0+
```

#### Step 4: Start JupyterLab

```bash
jupyter lab
```

### Advanced venv Setup with Development Tools

For a more complete development environment:

```bash
# 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

```bash
# 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:

```dockerfile
# 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.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

```bash
# 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`:

```yaml
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:

```bash
# 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:

```dockerfile
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.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

```bash
python --version     # Should show 3.10+
jupyter lab --version  # Should show 4.4.0+
```

### 2. Start JupyterLab

```bash
jupyter lab
```

### 3. Find runcell Extension

1. Look for the runcell extension in the **right sidebar**
2. Click on the runcell icon to activate
3. 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: run `jupyter lab stop` in a new terminal or press `Ctrl + C` in the running terminal, then start again with `jupyter lab`. You can also select **Restart Server** from the JupyterLab menu if available.
* Clear browser cache
* Verify JupyterLab version is 4.4.0+

#### Python Version Issues

```bash
# Check Python version
python --version

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

#### Permission Errors

```bash
# Install with user flag
pip install --user runcell

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

#### Docker Issues

```bash
# 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

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

#### Ubuntu/Debian

```bash
# 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

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

## Next Steps

Once runcell is installed and working:

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

## Support

If you encounter issues during setup:

1. Check the [troubleshooting section](#troubleshooting) above
2. Verify all prerequisites are met
3. Try a clean installation in a new environment
4. Check JupyterLab logs for error messages

***

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