RunCell.dev

Frequently Asked Questions

Common issues and solutions for runcell - Troubleshooting guide for installation and usage

Frequently Asked Questions

This FAQ covers the most common issues users encounter when installing and using runcell. If you can't find your answer here, check our Setup Guide or reach out for support.

Installation Issues

Q: I installed runcell but don't see the extension in JupyterLab

A: This is the most common issue. Here are the steps to resolve it:

Step 1: Restart JupyterLab Completely

runcell contains both frontend and backend components. After installation, you must restart JupyterLab completely:

# Stop JupyterLab (Ctrl+C in terminal)
# Then restart
jupyter lab

Step 2: Check Environment Mismatch

The issue often occurs when Jupyter and runcell are installed in different environments. Check if they're using the same Python/pip:

# Check which Python Jupyter is using
which jupyter
which python
which pip

# All should point to the same environment
# Example output (should be similar):
# /path/to/your-env/bin/jupyter
# /path/to/your-env/bin/python
# /path/to/your-env/bin/pip

If they point to different locations:

# Option 1: Install runcell in the same environment as Jupyter
# Activate the environment where Jupyter is installed
source /path/to/jupyter-env/bin/activate
pip install runcell

# Option 2: Install Jupyter in the same environment as runcell
# Activate the environment where runcell is installed
source /path/to/runcell-env/bin/activate
pip install jupyterlab

Step 3: Clear Browser Cache

Sometimes browser caching can cause issues:

  • Chrome/Safari: Ctrl+Shift+R (Cmd+Shift+R on Mac)
  • Firefox: Ctrl+F5 (Cmd+Shift+R on Mac)
  • Or use incognito/private browsing mode

Step 4: Check the Right Sidebar

Make sure you're looking in the right sidebar of JupyterLab, not the left sidebar or main menu.

Q: I get permission errors when installing runcell

A: Try these solutions:

# Option 1: Install for current user only
pip install --user runcell

# Option 2: Fix permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.local/

# Option 3: Use a virtual environment (recommended)
python -m venv runcell-env
source runcell-env/bin/activate  # macOS/Linux
# runcell-env\Scripts\activate  # Windows
pip install runcell jupyterlab

Q: Installation fails with "No module named 'xyz'" error

A: This usually indicates missing dependencies:

# Update pip first
pip install --upgrade pip

# Install with verbose output to see what's failing
pip install -v runcell

# If specific dependencies fail, install them separately
pip install jupyterlab>=4.0
pip install runcell

Environment Issues

Q: How do I check if I'm in the right environment?

A: Use these commands to verify your environment:

# Check current environment
echo $VIRTUAL_ENV  # Should show your venv path
conda info --envs  # If using conda

# Check Python and package locations
which python
which jupyter
which pip
python -c "import sys; print(sys.executable)"

# Check installed packages
pip list | grep runcell
pip list | grep jupyterlab

Q: I'm using conda but runcell isn't working

A: Even with conda, it's recommended to install runcell with pip:

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

# Install JupyterLab if not already installed
conda install -c conda-forge jupyterlab

# Install runcell with pip (not conda install)
pip install runcell

# Restart JupyterLab
jupyter lab

Q: I have multiple Python versions, which one should I use?

A: runcell requires Python 3.10+. Check your versions:

# Check all Python versions
python --version
python3 --version
python3.10 --version
python3.11 --version

# Use the appropriate version (3.10+)
python3.11 -m pip install runcell jupyterlab
python3.11 -m jupyter lab

JupyterLab Compatibility

Q: Can I use runcell with Jupyter Notebook (classic)?

A: No, runcell only supports JupyterLab 4.0+. The classic Jupyter Notebook interface is not supported.

To migrate from Jupyter Notebook to JupyterLab:

# Install JupyterLab
pip install jupyterlab

# Use JupyterLab instead of Notebook
jupyter lab  # instead of: jupyter notebook

Q: My JupyterLab version is older than 4.0

A: You need to upgrade JupyterLab:

# Check current version
jupyter lab --version

# Upgrade JupyterLab
pip install --upgrade jupyterlab

# If using conda
conda update -c conda-forge jupyterlab

# Verify upgrade
jupyter lab --version  # Should show 4.0+

Q: JupyterLab shows "Extension not compatible" error

A: This usually means version mismatch:

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

# Reinstall both with compatible versions
pip install --upgrade jupyterlab>=4.0
pip install --force-reinstall runcell

# Restart JupyterLab
jupyter lab

Docker Issues

Q: runcell doesn't work in my Docker container

A: Make sure your Dockerfile installs compatible versions:

# Ensure JupyterLab 4.0+ is installed
RUN pip install --no-cache-dir \
    jupyterlab>=4.0 \
    runcell

# Make sure to restart JupyterLab service after installation

Q: Docker container starts but I can't access JupyterLab

A: Check your Docker run command and port mapping:

# Correct way to run
docker run -p 8888:8888 \
  -v $(pwd):/home/jovyan/work \
  your-image-name

# Access via browser
http://localhost:8888

Usage Issues

Q: runcell extension loads but doesn't work properly

A: Try these troubleshooting steps:

# Check for JavaScript errors in browser console
# (F12 -> Console tab)

# Restart JupyterLab with verbose logging
jupyter lab --log-level=DEBUG

# Check if there are conflicting extensions
jupyter labextension list

Q: How do I know if runcell is working correctly?

A: Verify installation:

  1. Check the extension appears: Look for runcell icon in JupyterLab's right sidebar
  2. Test functionality: Click on the extension and see if it loads properly
  3. Check logs: No errors in browser console or JupyterLab logs
# Command line verification
pip show runcell
jupyter labextension list | grep runcell

Performance Issues

Q: JupyterLab is slow after installing runcell

A: This might be due to:

# Clear JupyterLab cache
jupyter lab clean

# Restart with cleared cache
jupyter lab

# If still slow, check for conflicting extensions
jupyter labextension list

Q: runcell extension takes long to load

A: Try these optimizations:

# Restart JupyterLab completely
# Clear browser cache
# Check available system memory
# Close other resource-intensive applications

System-Specific Issues

Q: Issues on macOS with Apple Silicon (M1/M2)

A: Make sure you're using compatible versions:

# Use Python 3.10+ (native or Rosetta)
python --version

# Install with pip (avoid conda for this package)
pip install runcell jupyterlab

# If still issues, try:
arch -arm64 pip install runcell

Q: Issues on Windows

A: Common Windows-specific solutions:

# Use Command Prompt or PowerShell (not Git Bash)
python -m pip install runcell jupyterlab

# If using Anaconda, launch from Anaconda Prompt
conda activate your-env
pip install runcell

Q: Issues on Linux with system Python

A: Avoid using system Python:

# Install pyenv or use virtual environments
python3 -m venv runcell-env
source runcell-env/bin/activate
pip install runcell jupyterlab

Getting Help

Q: None of these solutions work for me

A: If you're still having issues:

  1. Gather information:
# Create a debug report
echo "=== System Info ===" > debug.txt
python --version >> debug.txt
pip --version >> debug.txt
jupyter lab --version >> debug.txt
which python >> debug.txt
which jupyter >> debug.txt
pip list | grep -E "(runcell|jupyterlab)" >> debug.txt
echo "=== Environment ===" >> debug.txt
echo $PATH >> debug.txt
echo $VIRTUAL_ENV >> debug.txt
  1. Try a clean environment:
# Create fresh environment
python -m venv test-runcell
source test-runcell/bin/activate
pip install jupyterlab runcell
jupyter lab
  1. Check logs:
# Start JupyterLab with debug logging
jupyter lab --log-level=DEBUG

Quick Checklist

When runcell isn't working, go through this checklist:

  • Python version is 3.10 or higher
  • JupyterLab version is 4.0 or higher
  • Jupyter and runcell are in the same environment
  • JupyterLab was restarted after installation
  • Browser cache was cleared
  • Looking in the right sidebar of JupyterLab
  • No permission errors during installation
  • No conflicting extensions installed

Still having issues? The problem might be environment-specific. Try creating a fresh virtual environment and installing both JupyterLab and runcell together.