> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sphinx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Environment Setup

> Set up Python environments for Jupyter notebooks in VS Code using UV, venv, or remote servers

## Overview

A properly configured Python environment is essential for working with Sphinx and Jupyter notebooks. This guide covers setting up local environments using modern tools like UV and traditional venv, as well as connecting to remote Jupyter servers.

<Tip>
  **Recommendation:** Use [UV](https://docs.astral.sh/uv/) for new projects. It's significantly faster than pip and provides better dependency resolution.
</Tip>

### Python Installation

Before setting up environments, ensure Python 3.8 or higher is installed:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    # Using Homebrew (recommended)
    brew install python@3.11

    # Or download from python.org
    # https://www.python.org/downloads/
    ```
  </Tab>

  <Tab title="Windows">
    Download the installer from [python.org](https://www.python.org/downloads/) or use winget:

    ```powershell theme={null}
    # Using winget (Windows 10+)
    winget install Python.Python.3.11

    # During installation, check "Add Python to PATH"
    ```

    Verify installation:

    ```powershell theme={null}
    python --version
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt update
    sudo apt install python3 python3-pip python3-venv

    # Fedora
    sudo dnf install python3 python3-pip

    # Arch Linux
    sudo pacman -S python python-pip
    ```

    Verify installation:

    ```bash theme={null}
    python3 --version
    ```
  </Tab>
</Tabs>

***

## Local Environment Setup

<Tabs>
  <Tab title="UV (Recommended)">
    [UV](https://docs.astral.sh/uv/) is a fast Python package manager written in Rust that handles virtual environments and dependencies.

    ### Install UV

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        curl -LsSf https://astral.sh/uv/install.sh | sh
        ```
      </Tab>

      <Tab title="Windows">
        ```powershell theme={null}
        powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
        ```
      </Tab>

      <Tab title="Homebrew">
        ```bash theme={null}
        brew install uv
        ```
      </Tab>
    </Tabs>

    ### Create a Project with UV

    ```bash theme={null}
    # Create a new project directory
    mkdir my-analysis && cd my-analysis

    # Initialize a UV project (creates pyproject.toml)
    uv init

    # Create virtual environment and install data science packages
    uv add pandas numpy matplotlib seaborn scikit-learn scipy ipykernel
    ```

    ### Register the Kernel with Jupyter

    ```bash theme={null}
    # Activate the environment and register the kernel
    uv run python -m ipykernel install --user --name my-analysis --display-name "Python (my-analysis)"
    ```

    ### Project Structure

    After setup, your project should look like:

    ```text theme={null}
    my-analysis/
    ├── .venv/              # Virtual environment (managed by UV)
    ├── pyproject.toml      # Project dependencies
    ├── uv.lock             # Locked dependency versions
    └── notebooks/          # Your Jupyter notebooks
    ```

    <Note>
      UV automatically creates and manages the `.venv` directory. You don't need to activate it manually—use `uv run` to execute commands in the environment.
    </Note>

    ### Adding Packages Later

    ```bash theme={null}
    # Add a new package
    uv add plotly

    # Add a development dependency
    uv add --dev pytest

    # Sync environment with lock file
    uv sync
    ```
  </Tab>

  <Tab title="venv (Standard Library)">
    Python's built-in `venv` module creates lightweight virtual environments without additional tools.

    ### Create a Virtual Environment

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        # Create project directory
        mkdir my-analysis && cd my-analysis

        # Create virtual environment
        python3 -m venv .venv

        # Activate the environment
        source .venv/bin/activate

        # Upgrade pip
        pip install --upgrade pip
        ```
      </Tab>

      <Tab title="Windows">
        ```powershell theme={null}
        # Create project directory
        mkdir my-analysis && cd my-analysis

        # Create virtual environment
        python -m venv .venv

        # Activate the environment
        .venv\Scripts\activate

        # Upgrade pip
        pip install --upgrade pip
        ```
      </Tab>
    </Tabs>

    ### Install Data Science Packages

    ```bash theme={null}
    # Install common data science packages
    pip install pandas numpy matplotlib seaborn scikit-learn scipy

    # Install Jupyter kernel support
    pip install ipykernel

    # Register the kernel
    python -m ipykernel install --user --name my-analysis --display-name "Python (my-analysis)"
    ```

    ### Create a Requirements File

    ```bash theme={null}
    # Save current dependencies
    pip freeze > requirements.txt
    ```

    Your `requirements.txt` should include:

    ```text theme={null}
    pandas>=2.0.0
    numpy>=1.24.0
    matplotlib>=3.7.0
    seaborn>=0.12.0
    scikit-learn>=1.3.0
    scipy>=1.11.0
    ipykernel>=6.25.0
    ```

    ### Recreate Environment from Requirements

    ```bash theme={null}
    # Create fresh environment
    python3 -m venv .venv
    source .venv/bin/activate  # or .venv\Scripts\activate on Windows

    # Install from requirements
    pip install -r requirements.txt
    ```
  </Tab>

  <Tab title="Conda">
    Conda is popular in data science for managing environments and non-Python dependencies.

    ### Install Miniconda

    <Tabs>
      <Tab title="macOS">
        ```bash theme={null}
        # Using Homebrew
        brew install miniconda

        # Or download the installer
        # https://docs.conda.io/en/latest/miniconda.html
        ```
      </Tab>

      <Tab title="Windows">
        Download the [Windows installer](https://docs.conda.io/en/latest/miniconda.html) and run it, or use winget:

        ```powershell theme={null}
        winget install Anaconda.Miniconda3
        ```

        After installation, open **Anaconda Prompt** from the Start menu to use conda commands.
      </Tab>

      <Tab title="Linux">
        ```bash theme={null}
        # Download and install
        wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
        bash Miniconda3-latest-Linux-x86_64.sh

        # Follow the prompts, then restart your terminal
        ```
      </Tab>
    </Tabs>

    ### Create a Conda Environment

    ```bash theme={null}
    # Create environment with Python 3.11
    conda create -n my-analysis python=3.11 -y

    # Activate the environment
    conda activate my-analysis

    # Install data science packages
    conda install pandas numpy matplotlib seaborn scikit-learn scipy ipykernel -y

    # Register the kernel
    python -m ipykernel install --user --name my-analysis --display-name "Python (my-analysis)"
    ```

    ### Export Environment

    ```bash theme={null}
    # Export to YAML file
    conda env export > environment.yml
    ```

    ### Recreate from YAML

    ```bash theme={null}
    conda env create -f environment.yml
    ```
  </Tab>
</Tabs>

***

## VS Code Configuration

### Select Your Python Interpreter

1. Open VS Code Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Run **"Python: Select Interpreter"**
3. Choose your virtual environment (`.venv` or conda environment)

<Frame>
  VS Code should show your environment in the status bar, e.g., `Python 3.11.0 ('.venv': venv)`
</Frame>

### Select Jupyter Kernel

When you open a `.ipynb` file:

1. Click the kernel selector in the top-right corner
2. Select your registered kernel (e.g., "Python (my-analysis)")
3. The kernel should start and show as connected

<Warning>
  If your kernel doesn't appear, ensure you ran the `ipykernel install` command and restart VS Code.
</Warning>

### Recommended VS Code Extensions

Install these extensions for the best Jupyter experience:

| Extension                                                                               | Purpose                                |
| --------------------------------------------------------------------------------------- | -------------------------------------- |
| [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)          | Python language support                |
| [Jupyter](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)       | Notebook support (required for Sphinx) |
| [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) | Fast IntelliSense and type checking    |

***

## Remote Jupyter Server

Connect to a Jupyter server running on a remote machine, cloud instance, or HPC cluster.

### Start a Remote Jupyter Server

On the remote machine:

```bash theme={null}
# Install Jupyter
pip install jupyter

# Start server with remote access
jupyter notebook --no-browser --ip=0.0.0.0 --port=8888
```

The server will output a URL with a token:

```text theme={null}
http://127.0.0.1:8888/?token=abc123...
```

<Warning>
  **Security:** Never expose Jupyter servers to the public internet without authentication. Use SSH tunneling for secure connections.
</Warning>

### Connect VS Code to Remote Server

1. Open VS Code Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Run **"Jupyter: Specify Jupyter Server for Connections"**
3. Select **"Existing"**
4. Enter the server URL: `http://localhost:8888/?token=abc123...`
5. Your remote kernels should now appear in the kernel picker

### JupyterHub Connection

For enterprise JupyterHub deployments:

1. Get your JupyterHub URL (e.g., `https://hub.company.com`)
2. Follow the same connection steps as above
3. Authenticate with your JupyterHub credentials
4. Select from available hub-managed kernels

<Tip>
  Some JupyterHub deployments require an API token. Generate one from the JupyterHub web interface under **Token** settings.
</Tip>

***

## Best Practices

<AccordionGroup>
  <Accordion title="One environment per project">
    Avoid using a single global environment. Create dedicated environments for each project to prevent dependency conflicts and ensure reproducibility.

    ```bash theme={null}
    # Good: Project-specific environment
    my-project/.venv/

    # Bad: Global environment shared across projects
    ~/.global-venv/
    ```
  </Accordion>

  <Accordion title="Pin your dependencies">
    Always pin package versions for reproducible environments:

    **UV (pyproject.toml):**

    ```toml theme={null}
    [project]
    dependencies = [
        "pandas>=2.0.0,<3.0.0",
        "numpy>=1.24.0,<2.0.0",
    ]
    ```

    **pip (requirements.txt):**

    ```text theme={null}
    pandas==2.1.4
    numpy==1.26.3
    ```

    UV automatically creates a `uv.lock` file for exact reproducibility.
  </Accordion>

  <Accordion title="Use .gitignore for virtual environments">
    Never commit virtual environments to version control:

    ```text theme={null}
    # .gitignore
    .venv/
    venv/
    env/
    __pycache__/
    *.pyc
    *.pyo
    .ipynb_checkpoints/
    *.egg-info/
    dist/
    build/
    ```

    **Cross-platform note:** Use forward slashes (`/`) in `.gitignore` even on Windows—Git handles the conversion automatically.
  </Accordion>

  <Accordion title="Document your setup">
    Include setup instructions in your project README:

    ```markdown theme={null}
    ## Setup

    1. Install UV: `curl -LsSf https://astral.sh/uv/install.sh | sh`
    2. Install dependencies: `uv sync`
    3. Register kernel: `uv run python -m ipykernel install --user --name my-project`
    4. Open VS Code and select the kernel
    ```
  </Accordion>

  <Accordion title="Keep environments minimal">
    Only install packages you actually need. Large environments are slow to create and can have dependency conflicts.

    ```bash theme={null}
    # Good: Install what you need
    uv add pandas matplotlib

    # Avoid: Installing everything "just in case"
    uv add pandas numpy scipy matplotlib seaborn plotly bokeh altair ...
    ```
  </Accordion>

  <Accordion title="Use pyproject.toml for modern projects">
    `pyproject.toml` is the modern standard for Python project configuration:

    ```toml theme={null}
    [project]
    name = "my-analysis"
    version = "0.1.0"
    requires-python = ">=3.10"
    dependencies = [
        "pandas>=2.0.0",
        "matplotlib>=3.7.0",
        "ipykernel>=6.25.0",
    ]

    [project.optional-dependencies]
    dev = ["pytest", "black", "ruff"]
    ```
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Kernel not appearing in VS Code">
    1. Ensure `ipykernel` is installed in your environment
    2. Run the kernel install command:
       ```bash theme={null}
       python -m ipykernel install --user --name my-env --display-name "Python (my-env)"
       ```
    3. Restart VS Code
    4. Check **"Jupyter: Select Interpreter to Start Jupyter Server"** in Command Palette
  </Accordion>

  <Accordion title="Package import errors in notebook">
    The notebook might be using a different kernel than expected:

    1. Check the active kernel in the top-right of the notebook
    2. Ensure it matches your environment with the installed packages
    3. Restart the kernel after installing new packages
  </Accordion>

  <Accordion title="UV command not found">
    Add UV to your PATH:

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        # Add to ~/.zshrc or ~/.bashrc
        export PATH="$HOME/.cargo/bin:$PATH"
        ```

        Then restart your terminal or run `source ~/.zshrc`.
      </Tab>

      <Tab title="Windows">
        The UV installer should add it to PATH automatically. If not:

        1. Open **System Properties** → **Environment Variables**
        2. Under **User variables**, edit **Path**
        3. Add: `%USERPROFILE%\.cargo\bin`
        4. Click **OK** and restart your terminal

        Or use PowerShell:

        ```powershell theme={null}
        $env:Path += ";$env:USERPROFILE\.cargo\bin"
        [Environment]::SetEnvironmentVariable("Path", $env:Path, "User")
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Remote kernel disconnects frequently">
    * Check network stability
    * Increase Jupyter timeout settings on the server:
      ```bash theme={null}
      jupyter notebook --NotebookApp.shutdown_no_activity_timeout=3600
      ```
    * Consider using VS Code Remote - SSH extension for a more stable connection
  </Accordion>

  <Accordion title="Permission denied when installing kernel">
    Use the `--user` flag to install kernels in your user directory:

    ```bash theme={null}
    python -m ipykernel install --user --name my-env
    ```

    Or use `--prefix` for a specific location:

    ```bash theme={null}
    python -m ipykernel install --prefix=/path/to/kernels --name my-env
    ```
  </Accordion>

  <Accordion title="'python' is not recognized (Windows)">
    If you see this error on Windows:

    1. Ensure Python is installed: `winget install Python.Python.3.11`
    2. Check **Add Python to PATH** was selected during installation
    3. Manually add Python to PATH:
       * Open **System Properties** → **Environment Variables**
       * Under **User variables**, edit **Path**
       * Add: `C:\Users\YourUsername\AppData\Local\Programs\Python\Python311`
       * Add: `C:\Users\YourUsername\AppData\Local\Programs\Python\Python311\Scripts`
    4. Restart your terminal

    Alternatively, use the Python Launcher:

    ```powershell theme={null}
    py -m venv .venv
    py -m pip install package-name
    ```
  </Accordion>

  <Accordion title="Python command differences (Linux/Mac vs Windows)">
    **Linux/macOS:**

    * Use `python3` and `pip3` to avoid Python 2.x conflicts
    * Example: `python3 -m venv .venv`

    **Windows:**

    * Use `python` (Python 3 is the default)
    * Or use `py` launcher: `py -3.11 -m venv .venv`

    **Cross-platform script:**

    ```bash theme={null}
    # Works on all platforms
    python -m venv .venv  # or python3 on Linux/macOS
    ```
  </Accordion>
</AccordionGroup>

***

## Quick Reference

### UV Commands

| Command               | Description                     |
| --------------------- | ------------------------------- |
| `uv init`             | Initialize new project          |
| `uv add <package>`    | Add dependency                  |
| `uv remove <package>` | Remove dependency               |
| `uv sync`             | Sync environment with lock file |
| `uv run <command>`    | Run command in environment      |
| `uv lock`             | Update lock file                |

### venv Commands

| Command                         | Description            |
| ------------------------------- | ---------------------- |
| `python -m venv .venv`          | Create environment     |
| `source .venv/bin/activate`     | Activate (macOS/Linux) |
| `.venv\Scripts\activate`        | Activate (Windows)     |
| `deactivate`                    | Deactivate environment |
| `pip freeze > requirements.txt` | Export dependencies    |

### Kernel Commands

| Command                                            | Description            |
| -------------------------------------------------- | ---------------------- |
| `python -m ipykernel install --user --name <name>` | Register kernel        |
| `jupyter kernelspec list`                          | List installed kernels |
| `jupyter kernelspec uninstall <name>`              | Remove kernel          |