pixi description

2026-11-12 22:35:51 +00:00 · 2026-08-29 15:49:39 +02:00 · 2026-08-29 15:49:39 +02:00 · 1d30b1102c
commit 1d30b1102c
parent ab43185bb2
4 changed files with 113 additions and 11 deletions
--- a/book/installation-and-setup/figures/jupyterlab.png
+++ b/book/installation-and-setup/figures/jupyterlab.png
--- a/book/installation-and-setup/pixi.md
+++ b/book/installation-and-setup/pixi.md
@ -1,21 +1,49 @@
-# Installing and running with Pixi
+# Installing and running Teachbooks with Pixi

- Install pixi
+> Install Pixi once, and you don't have to worry about installing the correct Python version and TeachBooks dependencies yourself.

-In the root file of the TB:
+Pixi is a package management tool that allows you to install Python, TeachBooks, and other dependencies using a single `pixi.toml` file. We created this file for you, so you only need to install [pixi from here](https://pixi.prefix.dev/latest/installation/). Pixi is available for Windows, macOS, and Linux.

- run `pixi install`
+We present Pixi here as an alternative installation and workflow to the approach presented in the rest of this documentation. When using Pixi, you do not need to separately install Python, TeachBooks, JupyterLab, or manage a virtual environment. Simply start making your book using the [ten steps](https://teachbooks.tudelft.nl/jupyter-book-manual/draft/external/template/README.html#your-first-teachbook-using-the-github-template) and install the project environment as described below.

-This will install teachbooks and the most common dependecies. 
+> If you already have a TeachBooks project, download this [pixi.toml file](../../pixi.toml), place it in the root folder of your project, and follow the steps below.

-three tasks:
+
+
+Using the terminal, navigate to the root folder of your project and run `pixi install`. This will install all necessary software and packages - these are installed in the project folder in `.pixi/`.
+
+In the pixi.toml file we have created three tasks:
 - `pixi run editor` this will start jupyterlab as the editor for both markdown and jupyternotebooks
- `pixi run serve` starts a server
- `pixi run teachbooks` builds the book (equivalent to `teachbooks build book` as described here)
-
-
+- `pixi run server` starts a server
+- `pixi run teachbooks` builds the book (equivalent to `teachbooks build book` as described [here](https://teachbooks.tudelft.nl/jupyter-book-manual/draft/installation-and-setup/jupyter-book-setup.html#build-a-book))


+## Add dependencies
+In the pixi.toml file, we included some of the most used depencies. If you want to add packages, use `pixi add <packages>` or if it is only available through pypi, use `pixi add --pypi <packages>`. Pixi adds the dependency to your project and updates the environment.

 ## Editing with Jupyter lab
-Something about Jupyter lab
+As an alternative to VSC, JupyterLab can be used to edit of your Jupyter Notebook and Markdown files. Start JupyterLab by running `pixi run editor` 
+
+```{figure} figures/jupyterlab.png
+---
+width: 50%
+name: fig_juplab_editor 
+---
+Running `pixi run editor` opens jupyterlab as editor.
+```
+
+You can preview the content by rightclicking the markdown document and open with markdownpreviewer. Once finished with editing, go back to the terminal and hit `ctrl + c` to stop the Jupyter server.
+
+## Cleaning up an unused project
+
+The Pixi environment can take up considerable disk space. If you don't plan to work on your TeachBook for a while, you can remove the installed environment with:
+
+`pixi clean`
+
+This removes the software and packages installed in the project's .pixi/ folder. Your pixi.toml and pixi.lock files are kept, so you can recreate the environment later by running:
+
+`pixi install`
+
+```{note} 
+If you have multiple Teachbooks, it seems as if they all take a lot of memory. This isn't really the case as pixi makes smart use of links between them.
+```
--- a/pixi.lock
+++ b/pixi.lock
@ -229,6 +229,7 @@ environments:
      - pypi: https://files.pythonhosted.org/packages/37/86/d45756beaeb4b9b06125599b429451f8640b5db6f019d606f33c85743fd4/jupyter_book-1.0.4.post1-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/64/6b/67b87da9d36bff9df7d0efbd1a325fa372a43be7158effaf43ed7b22341d/jupyter_cache-1.0.1-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/f6/54/af203c61a0550c232ed5e859d2c98f3fe80d1248b6ea1c4d4d5621fa08c9/jupyterbook_patches-1.15.0-py3-none-any.whl
+      - pypi: https://files.pythonhosted.org/packages/2b/08/ad5d4d383807ca379c02b8fa94f744c30ea0929a9b3953a19b00bea52b8b/jupyterlab_myst-2.7.0-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/b5/40/23569737873cc9637fd488606347e9dd92b9fa37ba4fcda1f98ee5219a97/latexcodec-3.0.1-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/eb/3d/e34b19cd144071c583317268c4feb2c59c03ac57eef69753410c7abb11c0/linkify_it_py-2.1.1-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/42/d7/1ec15b46af6af88f19b8e5ffea08fa375d433c998b8a7639e76935c14f1f/markdown_it_py-3.0.0-py3-none-any.whl
@ -239,6 +240,8 @@ environments:
      - pypi: https://files.pythonhosted.org/packages/44/f6/775eb92e865b28cdb4ad1f2bed7a5446197516f76b58a950faa3be3fd08d/pybtex-0.26.1-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/11/b1/ce1f4596211efb5410e178a803f08e59b20bedb66837dcf41e21c54f9ec1/pybtex_docutils-1.0.3-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/e2/0d/8ba33fa83a7dcde13eb3c1c2a0c1cc29950a048bfed6d9b0d8b6bd710b4c/pydata_sphinx_theme-0.16.1-py3-none-any.whl
+      - pypi: https://files.pythonhosted.org/packages/3e/b9/3766cc361d93edb2ce81e2e1f87dd98f314d7d513877a342d31b30741680/pypng-0.20220715.0-py3-none-any.whl
+      - pypi: https://files.pythonhosted.org/packages/37/61/f07226075c347897937d4086ef8e55f0a62ae535e28069884ac68d979316/PyQRCode-1.2.1.tar.gz
      - pypi: https://files.pythonhosted.org/packages/b8/0c/51f6841f1d84f404f92463fc2b1ba0da357ca1e3db6b7fbda26956c3b82a/ruamel_yaml-0.19.1-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/95/9c/c510029fc6ef33a6275cd2c5d3cecd6613dfd6aa401d57c54f1c18852ccf/setuptools-84.0.0-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/4c/07/2ebca9b11fb9be7340a818d8d6f63feaebb146be2c4afbd6061701d6df6e/snowballstemmer-3.1.1-py3-none-any.whl
@ -284,6 +287,7 @@ environments:
      - pypi: git+https://github.com/TeachBooks/TeachBooks-Favourites.git#ad0f301f83effb9322a5460f444d88878b30a75b
      - pypi: https://files.pythonhosted.org/packages/7f/24/77b78c112c60e2ddb16351e77f9a108628a6c3c18a618815112d79d374a2/teachbooks_fetch-0.0.1-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/01/d0/99a7a3e3cce5d83566567c484cce9f2c5874c22da4cf2d420647233dbc81/teachbooks_questions-0.2.1-py3-none-any.whl
+      - pypi: https://files.pythonhosted.org/packages/3e/70/86d1bd35bcf06cdb0aaf59cdec3932cec21750dd276b69856221e25ea6d5/teachbooks_sphinx_grasple-1.3.0-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/05/77/8c5a7237bc99221408f12b629210b8f2176bcccfca916c09edfa8eb048e3/teachbooks_sphinx_tippy-1.0.15-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/24/74/f356db22f82eba6fd559128ae31222564f1e9e1e8b46a6ff93262621a9a2/teachbooks_zoomies-0.2.4-py3-none-any.whl
      - pypi: https://files.pythonhosted.org/packages/61/73/d21edf5b204d1467e06500080a50f79d49ef2b997c79123a536d4a17d97c/uc_micro_py-2.0.0-py3-none-any.whl
@ -1487,6 +1491,18 @@ packages:
  - pkg:pypi/jupyterlab?source=compressed-mapping
  size: 13178193
  timestamp: 1786398793317
+- pypi: https://files.pythonhosted.org/packages/2b/08/ad5d4d383807ca379c02b8fa94f744c30ea0929a9b3953a19b00bea52b8b/jupyterlab_myst-2.7.0-py3-none-any.whl
+  name: jupyterlab-myst
+  version: 2.7.0
+  sha256: 7c66aae898a5b0db84b1d4b83fa68d5d37f846b4f891621de78abb960678e70e
+  requires_dist:
+  - jupyter-server>=2.0.1,<3 ; sys_platform != 'emscripten'
+  - coverage ; extra == 'test'
+  - pytest ; extra == 'test'
+  - pytest-asyncio ; extra == 'test'
+  - pytest-cov ; extra == 'test'
+  - pytest-jupyter[server]>=0.6.0 ; extra == 'test'
+  requires_python: '>=3.8'
 - conda: https://conda.anaconda.org/conda-forge/noarch/jupyterlab_pygments-0.3.0-pyhd8ed1ab_2.conda
  sha256: dc24b900742fdaf1e077d9a3458fd865711de80bca95fe3c6d46610c532c6ef0
  md5: fd312693df06da3578383232528c468d
@ -2781,6 +2797,16 @@ packages:
  - pkg:pypi/pyparsing?source=hash-mapping
  size: 110893
  timestamp: 1769003998136
+- pypi: https://files.pythonhosted.org/packages/3e/b9/3766cc361d93edb2ce81e2e1f87dd98f314d7d513877a342d31b30741680/pypng-0.20220715.0-py3-none-any.whl
+  name: pypng
+  version: 0.20220715.0
+  sha256: 4a43e969b8f5aaafb2a415536c1a8ec7e341cd6a3f957fd5b5f32a4cfeed902c
+- pypi: https://files.pythonhosted.org/packages/37/61/f07226075c347897937d4086ef8e55f0a62ae535e28069884ac68d979316/PyQRCode-1.2.1.tar.gz
+  name: pyqrcode
+  version: 1.2.1
+  sha256: fdbf7634733e56b72e27f9bce46e4550b75a3a2c420414035cae9d9d26b234d5
+  requires_dist:
+  - pypng>=0.0.13 ; extra == 'png'
 - conda: https://conda.anaconda.org/conda-forge/win-64/pyside6-6.11.2-py314h447aaf0_0.conda
  sha256: bf1553eebc31e8ba04689639e8ce235c3df5317414f0c4a11417f238297f1b17
  md5: 7c3ccff96dbc9f8e3c40142c7594ec34
@ -3892,6 +3918,52 @@ packages:
  requires_dist:
  - sphinx
  requires_python: '>=3.10'
+- pypi: https://files.pythonhosted.org/packages/3e/70/86d1bd35bcf06cdb0aaf59cdec3932cec21750dd276b69856221e25ea6d5/teachbooks_sphinx_grasple-1.3.0-py3-none-any.whl
+  name: teachbooks-sphinx-grasple
+  version: 1.3.0
+  sha256: 414e20e9036a47b24d3d09b34fa16cf3f7b2758f9e24fb47da0496b3d70c1878
+  requires_dist:
+  - pypng
+  - pyqrcode
+  - sphinx-book-theme
+  - sphinx>=4
+  - beautifulsoup4 ; extra == 'all'
+  - black ; extra == 'all'
+  - coverage ; extra == 'all'
+  - docutils>=0.15,<0.19 ; extra == 'all'
+  - flake8>=3.7.0,<3.8.0 ; extra == 'all'
+  - matplotlib ; extra == 'all'
+  - myst-nb~=0.17.1 ; extra == 'all'
+  - pre-commit ; extra == 'all'
+  - pypng ; extra == 'all'
+  - pyqrcode ; extra == 'all'
+  - pytest-cov ; extra == 'all'
+  - pytest-regressions ; extra == 'all'
+  - pytest>=3.6,<4 ; extra == 'all'
+  - sphinx-book-theme ; extra == 'all'
+  - sphinx-exercise ; extra == 'all'
+  - sphinx>=4,<6 ; extra == 'all'
+  - texsoup ; extra == 'all'
+  - black ; extra == 'code-style'
+  - flake8>=3.7.0,<3.8.0 ; extra == 'code-style'
+  - pre-commit ; extra == 'code-style'
+  - myst-nb~=0.17.1 ; extra == 'rtd'
+  - sphinx-book-theme ; extra == 'rtd'
+  - sphinx-exercise ; extra == 'rtd'
+  - sphinx>=4,<6 ; extra == 'rtd'
+  - beautifulsoup4 ; extra == 'testing'
+  - coverage ; extra == 'testing'
+  - docutils>=0.15,<0.19 ; extra == 'testing'
+  - matplotlib ; extra == 'testing'
+  - myst-nb~=0.17.1 ; extra == 'testing'
+  - pypng ; extra == 'testing'
+  - pyqrcode ; extra == 'testing'
+  - pytest-cov ; extra == 'testing'
+  - pytest-regressions ; extra == 'testing'
+  - pytest>=3.6,<4 ; extra == 'testing'
+  - sphinx>=4,<6 ; extra == 'testing'
+  - texsoup ; extra == 'testing'
+  requires_python: '>=3.8'
 - pypi: https://files.pythonhosted.org/packages/05/77/8c5a7237bc99221408f12b629210b8f2176bcccfca916c09edfa8eb048e3/teachbooks_sphinx_tippy-1.0.15-py3-none-any.whl
  name: teachbooks-sphinx-tippy
  version: 1.0.15
--- a/pixi.toml
+++ b/pixi.toml
@ -21,3 +21,5 @@ teachbooks = ">=0.2.5, <0.3"
 teachbooks-favourites = { git = "https://github.com/TeachBooks/TeachBooks-Favourites.git" }
 sphinx-inline-tabs = ">=2025.12.21.14, <2026"
 sphinx-apa-references = ">=1.0.1, <2"
+jupyterlab-myst = ">=2.7.0, <3"
+teachbooks-sphinx-grasple = ">=1.3.0, <2"