# Frequently Asked Questions > Common issues and solutions for runcell - Troubleshooting guide for installation and usage Canonical HTML: https://www.runcell.dev/docs/faq 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](https://www.runcell.dev/docs/setup.md) 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**: ```bash # Stop JupyterLab using one of these methods: # Option 1: Run in a new terminal window jupyter lab stop # Option 2: Press Ctrl+C in the terminal where JupyterLab is running # Then restart jupyter lab ``` You can also select **Restart Server** from the JupyterLab menu if available. #### 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: ```bash # 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:** ```bash # 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: ```bash # 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: ```bash # 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.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: ```bash # 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: ```bash # 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: ```bash # 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.4.0+**. The classic Jupyter Notebook interface is not supported. To migrate from Jupyter Notebook to JupyterLab: ```bash # Install JupyterLab pip install jupyterlab # Use JupyterLab instead of Notebook jupyter lab # instead of: jupyter notebook ``` ### Q: My JupyterLab version is older than 4.4.0 **A:** You need to upgrade JupyterLab: ```bash # 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.4.0+ ``` ### Q: JupyterLab shows "Extension not compatible" error **A:** This usually means version mismatch: ```bash # Check versions python --version # Should be 3.10+ jupyter lab --version # Should be 4.4.0+ # Reinstall both with compatible versions pip install --upgrade jupyterlab>=4.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: ```dockerfile # Ensure JupyterLab 4.4.0+ is installed RUN pip install --no-cache-dir \ jupyterlab>=4.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: ```bash # 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: ```bash # 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 ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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**: ```bash # 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 ``` 2. **Try a clean environment**: ```bash # Create fresh environment python -m venv test-runcell source test-runcell/bin/activate pip install jupyterlab runcell jupyter lab ``` 3. **Check logs**: ```bash # 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.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.