Setup Guide
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!