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 labStep 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/pipIf 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 jupyterlabStep 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 jupyterlabQ: 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 runcellEnvironment 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 jupyterlabQ: 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 labQ: 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 labJupyterLab 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 notebookQ: 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 labDocker 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 installationQ: 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:8888Usage 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 listQ: How do I know if runcell is working correctly?
A: Verify installation:
- Check the extension appears: Look for runcell icon in JupyterLab's right sidebar
- Test functionality: Click on the extension and see if it loads properly
- Check logs: No errors in browser console or JupyterLab logs
# Command line verification
pip show runcell
jupyter labextension list | grep runcellPerformance 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 listQ: runcell extension takes long to load
A: Try these optimizations:
# Restart JupyterLab completely
# Clear browser cache
# Check available system memory
# Close other resource-intensive applicationsSystem-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 runcellQ: 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 runcellQ: 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 jupyterlabGetting Help
Q: None of these solutions work for me
A: If you're still having issues:
- 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- Try a clean environment:
# Create fresh environment
python -m venv test-runcell
source test-runcell/bin/activate
pip install jupyterlab runcell
jupyter lab- Check logs:
# Start JupyterLab with debug logging
jupyter lab --log-level=DEBUGQuick 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.