Document uv-with-Jupyter workflows

docs/guides/index.md

@@ -10,6 +10,7 @@ Check out one of the core guides to get started:
 Learn how to integrate uv with other software:
 
 - [Using in Docker images](./integration/docker.md)
+- [Using with Jupyter](./integration/jupyter.md)
 - [Using with pre-commit](./integration/pre-commit.md)
 - [Using in GitHub Actions](./integration/github.md)
 - [Using with alternative package indexes](./integration/alternative-indexes.md)

docs/guides/integration/jupyter.md

@@ -0,0 +1,45 @@
+# Using uv with Jupyter
+
+## As a standalone tool...
+
+If you're working within a [project](../../concepts/projects.md), you can kick off a Jupyter server
+with access to the project's virtual environment via the following:
+
+```console
+$ uv run --with jupyter jupyter notebook
+```
+
+Within the notebook, you can then import your project's modules as you would in any other `uv run`
+invocation. For example, if your project depends on `requests`, `import requests` will import
+`requests` from the project's virtual environment.
+
+While `jupyter` itself is installed in an isolated environment when used via
+`uv run --with jupyter`, within the notebook, `!uv add` and related commands will modify the
+_project's_ environment.
+
+For example, running `!uv add pydantic` from within a notebook will add `pydantic` to the project's
+dependencies and virtual environment, such that `import pydantic` will work immediately, without
+further configuration or a server restart.
+
+!!! note
+
+    Since the Jupyter server is running in an isolated virtual environment, `!uv pip install` will install package's
+    into _Jupyter's_ environment, not the project environment. Such dependencies may disappear on subsequent `jupyter`
+    invocations. To install packages into the project environment, use `!uv add`.
+
+If you're working with a notebook that relies on pip (e.g., via the `%pip` magic), you can include
+pip in your project's virtual environment by running `uv venv --seed` prior to starting the Jupyter
+server. For example, given:
+
+```console
+$ uv venv --seed
+$ uv run --with jupyter jupyter notebook
+```
+
+Subsequent `%pip install` invocations within the notebook will install packages into the project's
+virtual environment. However, such modifications will _not_ be reflected in the project's
+`pyproject.toml` or `uv.lock` files.
+
+## As a project dependency...
+
+## Within VS Code...

mkdocs.template.yml

@@ -109,6 +109,7 @@ nav:
   - Integration guides:
       - guides/integration/index.md
       - Docker: guides/integration/docker.md
+      - Jupyter: guides/integration/jupyter.md
       - GitHub Actions: guides/integration/github.md
       - Pre-commit: guides/integration/pre-commit.md
       - FastAPI: guides/integration/fastapi.md