> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# Jupyter Integration

> Use uv with Jupyter notebooks for interactive computing and data analysis

Integrate uv with Jupyter notebooks for interactive Python development, data analysis, and visualization with full project environment support.

## Using Jupyter in a Project

Run Jupyter with access to your project's virtual environment:

```bash theme={null}
uv run --with jupyter jupyter lab
```

This starts Jupyter Lab at [http://localhost:8888/lab](http://localhost:8888/lab) with access to your project's dependencies.

### Importing Project Dependencies

Within a notebook, you can import your project's modules directly:

```python theme={null}
import requests  # Imports from project's virtual environment
import pandas as pd
from myproject import my_module
```

## Creating a Kernel

For projects requiring package installation from notebooks, create a dedicated kernel:

<Steps>
  <Step title="Add ipykernel as dev dependency">
    ```bash theme={null}
    uv add --dev ipykernel
    ```
  </Step>

  <Step title="Create the kernel">
    ```bash theme={null}
    uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=project
    ```

    Replace `project` with your desired kernel name.
  </Step>

  <Step title="Start Jupyter">
    ```bash theme={null}
    uv run --with jupyter jupyter lab
    ```
  </Step>

  <Step title="Select kernel in notebook">
    When creating a new notebook, select the `project` kernel from the kernel dropdown menu.
  </Step>
</Steps>

### Installing Packages with a Kernel

Once the kernel is configured, install packages from within notebooks:

```python theme={null}
# Add to project dependencies (updates pyproject.toml and uv.lock)
!uv add pydantic

# Install to virtual environment only (no project updates)
!uv pip install pydantic
```

Both commands make the package immediately available:

```python theme={null}
import pydantic
```

## Without a Kernel

You can still install packages without creating a kernel, but with some caveats:

### Using uv add

```python theme={null}
# Modifies project environment and files
!uv add pydantic
import pydantic  # Works immediately
```

### Using uv pip install

```python theme={null}
# Installs to Jupyter's environment (temporary)
!uv pip install pydantic
```

<Warning>
  Without a kernel, `!uv pip install` installs packages into Jupyter's isolated environment, not your project. These packages may disappear when Jupyter restarts.
</Warning>

### Using pip Magic with Seed Environment

For notebooks using the `%pip` magic:

<Steps>
  <Step title="Create seeded virtual environment">
    ```bash theme={null}
    uv venv --seed
    ```
  </Step>

  <Step title="Start Jupyter">
    ```bash theme={null}
    uv run --with jupyter jupyter lab
    ```
  </Step>

  <Step title="Use pip magic in notebooks">
    ```python theme={null}
    %pip install requests
    import requests
    ```

    <Note>
      Packages installed with `%pip` won't be reflected in `pyproject.toml` or `uv.lock`.
    </Note>
  </Step>
</Steps>

## Standalone Jupyter

Run Jupyter without a project for ad-hoc analysis:

```bash theme={null}
uv tool run jupyter lab
```

This creates an isolated Jupyter environment unrelated to any project.

## Non-Project Virtual Environments

Use Jupyter in a virtual environment without a project structure:

<Tabs>
  <Tab title="macOS and Linux">
    ```bash theme={null}
    uv venv --seed
    uv pip install pydantic jupyterlab
    .venv/bin/jupyter lab
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    uv venv --seed
    uv pip install pydantic jupyterlab
    .venv\Scripts\jupyter lab
    ```
  </Tab>
</Tabs>

Install packages using either method:

```python theme={null}
!uv pip install requests
# or
!pip install requests
```

## VS Code Integration

Use Jupyter notebooks within VS Code with uv-managed projects:

<Steps>
  <Step title="Create project with ipykernel">
    ```bash theme={null}
    uv init project
    cd project
    uv add --dev ipykernel
    ```
  </Step>

  <Step title="Open in VS Code">
    ```bash theme={null}
    code .
    ```
  </Step>

  <Step title="Create notebook">
    Open the command palette and select "Create: New Jupyter Notebook".
  </Step>

  <Step title="Select kernel">
    When prompted for a kernel, choose "Python Environments" and select your virtual environment:

    * macOS/Linux: `.venv/bin/python`
    * Windows: `.venv\Scripts\python`
  </Step>
</Steps>

### Installing Packages in VS Code

For full environment manipulation, add uv as a dev dependency:

```bash theme={null}
uv add --dev uv
```

Then use in notebooks:

```python theme={null}
# Add to project dependencies
!uv add pydantic

# Install without updating project files
!uv pip install pydantic
```

<Note>
  VS Code requires `ipykernel` in the project environment. If you prefer not to add it as a dev dependency, install it directly: `uv pip install ipykernel`
</Note>

## Common Workflows

### Data Science Project

```bash theme={null}
# Set up project
uv init data-analysis
cd data-analysis
uv add pandas numpy matplotlib seaborn
uv add --dev ipykernel jupyter

# Create kernel
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=data-analysis

# Start Jupyter
uv run jupyter lab
```

### Quick Exploration

```bash theme={null}
# Create temporary environment
uv venv --seed
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install tools
uv pip install jupyterlab pandas

# Start Jupyter
jupyter lab
```

### Reproducible Research

```bash theme={null}
# Project with locked dependencies
uv init research-project
cd research-project
uv add pandas numpy scipy matplotlib jupyter ipykernel

# Lock dependencies
uv lock

# Share with collaborators (they run)
uv sync --locked
uv run jupyter lab
```

## Best Practices

* **Use kernels** for projects requiring package installation from notebooks
* **Pin Jupyter version** in `pyproject.toml` for reproducibility
* **Use `uv add`** to ensure dependencies are tracked in your project
* **Avoid `%pip magic`** unless using a seeded environment
* **Add ipykernel** as a dev dependency for VS Code compatibility
* **Create kernel per project** to avoid environment conflicts