kernel

Author: dwillis

docs/src/appendix/index.md

@@ -348,3 +348,70 @@ code .
 ```
 
 Once VS Code is open, you can create Jupyter notebooks directly in the editor and run them with the full notebook experience. You should now be able to pick up with the [VS Code tutorial](../notebook.md) and start working from there.
+
+## Troubleshooting Python Environments and Kernels
+
+If you're experiencing issues with importing packages or running code, the problem is often related to Python environment or kernel selection. Here are the most common issues and solutions:
+
+### "ModuleNotFoundError: No module named 'pandas'" (or other packages)
+
+**Cause**: VS Code is using a different Python environment than where you installed packages.
+
+**Solutions**:
+1. **Check Python Interpreter** (for .py files):
+ - Press `Ctrl+Shift+P` → "Python: Select Interpreter"
+ - Choose the interpreter where you installed packages
+ - Verify in the status bar (bottom-left of VS Code)
+
+2. **Check Jupyter Kernel** (for .ipynb files):
+ - Click kernel name in top-right of notebook
+ - Select the same Python environment where packages are installed
+ - Look for kernel paths matching your installation method (uv, conda, etc.)
+
+### Kernel Won't Start or Keeps Disconnecting
+
+**Solutions**:
+1. **Refresh Python Interpreters**:
+ - Press `Ctrl+Shift+P` → "Python: Refresh"
+ - Try selecting kernel again
+
+2. **Restart VS Code**:
+ - Close and reopen VS Code
+ - Reopen your notebook and select kernel
+
+3. **Check Python Installation**:
+ - Ensure Python and jupyter are properly installed
+ - For uv users: run `uv add jupyter` in your project
+ - For conda users: run `conda install jupyter`
+
+### Multiple Python Installations Confusion
+
+**If you have conda, uv, and system Python**:
+1. **Decide on one approach** for this tutorial
+2. **Install all packages in the same environment**
+3. **Always select the matching interpreter/kernel**
+4. **Use consistent commands** (don't mix `pip`, `conda`, and `uv`)
+
+### Environment Path Issues
+
+**Check these common locations**:
+- **uv projects**: Look for `.venv` folder in your project directory
+- **conda**: Look for `anaconda3` or `miniconda3` in paths
+- **system Python**: Usually `/usr/bin/python` or `/usr/local/bin/python`
+
+### Quick Verification Steps
+
+Before running tutorial code:
+1. **Open a new terminal in VS Code** (`View > Terminal`)
+2. **Test imports**:
+ ```python
+ python -c "import pandas; print('✅ pandas works')"
+ python -c "import matplotlib; print('✅ matplotlib works')"
+ python -c "import jupyter; print('✅ jupyter works')"
+ ```
+3. **If any fail**: Reinstall packages in your current environment
+4. **Match VS Code selection**: Ensure interpreter/kernel matches this environment
+
+```{tip}
+**Golden Rule**: The Python interpreter (status bar) and Jupyter kernel (notebook top-right) should always point to the same environment where you installed pandas, matplotlib, seaborn, and altair.
+```

docs/src/notebook.md

@@ -16,6 +16,14 @@ Let's start by creating your first Python file. In VS Code:
 
 ```{note}
 If VS Code prompts you to select a Python interpreter, choose the Python installation you set up in the previous chapter. This tells VS Code which Python environment to use when running your code.
+
+**How to select the right interpreter:**
+1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
+2. Type "Python: Select Interpreter" 
+3. Choose the Python installation where you installed packages (pandas, matplotlib, etc.)
+4. Look for the interpreter path that matches your setup (e.g., `.venv`, `anaconda3`, or system Python)
+
+The selected interpreter will be shown in the bottom-left status bar of VS Code.
 ```
 
 Now you're ready to write your first line of Python code. VS Code provides an excellent environment for both learning and professional Python development.
@@ -195,13 +203,47 @@ In addition to interactive Python files, VS Code also supports traditional Jupyt
 
 This creates a notebook file where you can add both code and markdown cells, just like in traditional Jupyter environments, but with all the benefits of VS Code's editor features.
 
+### Selecting the Right Kernel
+
+When you create or open a notebook, you need to select a Python kernel (the engine that runs your code):
+
+1. **Automatic Selection**: VS Code may automatically select a kernel based on your workspace
+2. **Manual Selection**: Click the kernel name in the **top-right corner** of the notebook
+3. **Choose Your Kernel**: Select the Python environment where you installed your packages:
+ - Look for the same Python path you selected as your interpreter
+ - If using uv: Choose the kernel from your project's `.venv` folder
+ - If using Anaconda: Choose the anaconda/miniconda kernel
+ - The kernel name should show the Python version and environment path
+
+4. **Verify Connection**: A green dot next to the kernel name means it's connected and ready to run code
+
+### Common Kernel Issues and Solutions
+
+**Problem**: "ModuleNotFoundError" when importing pandas or other packages
+
+**Solution**: 
+1. Check that you're using the correct kernel (top-right of notebook)
+2. Verify packages are installed in that environment
+3. Restart the kernel: Click kernel name → "Restart Kernel"
+
+**Problem**: Kernel won't start or keeps disconnecting
+
+**Solution**:
+1. Use Command Palette → "Python: Refresh"
+2. Try selecting a different kernel, then switch back
+3. Close and reopen the notebook file
+
 The notebook interface in VS Code allows you to:
 - Add code and markdown cells
 - Run cells individually or all at once
 - View rich output including plots and tables
 - Export to various formats
 - Use VS Code's powerful editing features
 
+```{tip}
+**Quick Check**: Before running any code, make sure the kernel name in the top-right shows the same Python environment where you installed your packages. This prevents import errors and ensures your code runs correctly.
+```
+
 ```{note}
 This tutorial includes a complete collection of interactive Jupyter notebooks that you can run directly in VS Code. You can find them in the [Interactive Notebooks](notebooks/index.md) section. These notebooks contain the same content as the tutorial chapters but in an interactive format where you can run the code and see the results immediately.
 ```

docs/src/notebooks/index.md

@@ -14,9 +14,15 @@ Make sure you've completed the [VS Code Setup](../vscode_setup.md) before starti
 
 1. **Download or clone** this repository to your local machine
 2. **Open VS Code** and navigate to the project folder
-3. **Open any notebook** by clicking on the `.ipynb` files in the `docs/src/notebooks/` directory
-4. **Run cells sequentially** by clicking the play button or pressing `Shift+Enter`
-5. **Experiment** by modifying the code and running your changes
+3. **Select the correct Python environment** in VS Code (see [setup guide](../vscode_setup.md))
+4. **Open any notebook** by clicking on the `.ipynb` files in the `docs/src/notebooks/` directory
+5. **Choose the right kernel** when prompted (should match your Python environment with packages installed)
+6. **Run cells sequentially** by clicking the play button or pressing `Shift+Enter`
+7. **Experiment** by modifying the code and running your changes
+
+```{important}
+**Before running any notebook**: Make sure you've selected the correct Python kernel (top-right corner of the notebook). It should be the same environment where you installed pandas, matplotlib, seaborn, and altair. If you see import errors, double-check your kernel selection.
+```
 
 Each notebook is self-contained and includes all necessary imports and data loading, so you can start with any chapter that interests you.
 

docs/src/vscode_setup.md

@@ -196,4 +196,43 @@ This creates a new `.ipynb` notebook file where you can add cells and run them i
 - Cell execution controls
 - Markdown and code cells
 
+## Selecting the Right Python Environment
+
+After installing packages, it's crucial to ensure VS Code uses the correct Python environment. This is especially important if you have multiple Python installations.
+
+### For Python Files (.py)
+
+When working with Python files, VS Code needs to know which Python interpreter to use:
+
+1. **Automatic Selection**: VS Code usually detects your Python installation automatically
+2. **Manual Selection**: If needed, press `Ctrl+Shift+P` (or `Cmd+Shift+P`) and type "Python: Select Interpreter"
+3. **Choose Your Environment**: Select the Python installation that has your packages installed:
+ - If using uv: Look for the interpreter in your project's `.venv` folder
+ - If using Anaconda: Choose the anaconda or miniconda interpreter
+ - If using system Python: Choose the global Python installation
+
+4. **Verify Selection**: Check the bottom-left status bar - it should show your selected Python version
+
+### For Jupyter Notebooks (.ipynb)
+
+Notebooks use "kernels" (similar to interpreters) to run code:
+
+1. **Initial Kernel Selection**: When you create or open a notebook, VS Code may prompt you to select a kernel
+2. **Manual Kernel Selection**: Click the kernel name in the top-right corner of the notebook to change it
+3. **Choose the Right Kernel**: Select the same Python environment where you installed packages
+4. **Verify Connection**: A green dot next to the kernel name means it's connected and ready
+
+### Troubleshooting Environment Issues
+
+If your imports don't work or packages aren't found:
+
+1. **Check Active Environment**: Verify VS Code is using the environment where you installed packages
+2. **Restart Kernel**: In notebooks, use "Restart Kernel" from the kernel menu
+3. **Refresh Interpreters**: Use Command Palette → "Python: Refresh" to update the interpreter list
+4. **Reinstall Packages**: If still having issues, reinstall packages in the correct environment
+
+```{tip}
+**Pro tip**: The status bar (bottom of VS Code) always shows your active Python interpreter. Make sure it matches the environment where you installed your packages!
+```
+
 Now you're ready to start learning Python for data analysis! The next chapter will introduce you to working with Jupyter notebooks in VS Code.