wxGUI: Support for Jupyter-based workflows#5901
wxGUI: Support for Jupyter-based workflows#5901lindakarlovska wants to merge 85 commits intoOSGeo:mainfrom
Conversation
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
from
be55385 to
817795e
Compare
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
github-actions
bot
added
GUI
|
Just set up the discussion page for the notebook working directory topic and workflows topic in general: #5909. |
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
from
3a3b7e7 to
55974d3
Compare
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
2 times, most recently
from
968784b to
9d30c42
Compare
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
from
65e8ea7 to
08a1f06
Compare
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
3 times, most recently
from
45af740 to
adf7898
Compare
|
Small note: Under Gentoo GNU/Linux distribution I get error message when I hit Start Jupyter Notebook tool button: I have install wxPython 4.x.x version: wxPython x11-libs/wxGTK library USE flags: dev-python/wxpython library USE flags: |
|
When I hit JupyterLab tool button from the Jupyter notebook toolbar, GRASS GIS window was killed. 
Jupyter Interactive Notebook version =dev-python/notebook-7.4.7 |
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
from
2c2788d to
36fa2c4
Compare
To keep things consistent with the Windows behavior, in 2d7b550 I added a check for wx.html2 as well. When it’s not available, the Jupyter button is disabled and shows a message explaining why. |
|
@tmszi thanks very much for the review! and sorry for the later response. @petrasovaa could you also make the review please so that we can merge it and incorporate this feature to the 8.5 version? |
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
from
842ff18 to
590df4f
Compare
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
from
31b2a2b to
ff48065
Compare
It was not actually caused by a different notebook or lab versions but by the fact that I have nbclassic installed which means that my InterfaceSwitcher looks different (it is a dropdown "Open In.." menu where two options are: nbclassic and jupyterlab - and it is a different JS class). I made the switcher more general - all these switchers should have the same name regardless of their classes. Does that work for you now @petrasovaa ? |
Yes, that seems to work! |
petrasovaa
left a comment
petrasovaa
left a comment
There was a problem hiding this comment.
Let's merge this. Any chance we could test it on Windows?
wenzeslaus
left a comment
wenzeslaus
left a comment
There was a problem hiding this comment.
This is good in terms of the code and it will need to be evaluated further in the wild. (Almost good to go.)
It would be great if someone who actually is in the target user group would evaluate this (now or after the merge). I'm using notebooks a lot, so I may also use them this way, but it will not change anything about how I do zero-install workshops or classes with things like Colab and Binder. My understanding is that Linda is trying to make impact in context where GRASS is used with GUI and without notebooks. I'm guessing @landam @pesekon2 others?
One small change still, I came up with a simpler, and hopefully also more informative, way of presenting the different links in the documentation. While the change is small in scale, it shows what is absolutely critical here: We should very carefully communicate what this is for and avoid creating a notion that one has to use the GUI in order to use GRASS+notebooks or that this is the integration of GRASS and Jupyter (it is the integration of notebooks into the GUI of GRASS).
Currently I am working on it, it is a big pain in general. I will be more specific soon. |
|
I am on holiday just with my phone, with no option to test it. If it stays open until late April, I can squeeze a quick test there after my arrival but unfortunately, no way to do it earlier at my side. Sorry. But I fully agree with @wenzeslaus 's comment on making it clear that this is not the only nor mandatory way to use the notebooks within the GRASS environment. |
…THON variable together with sys.executable used for all platforms
@petrasovaa, @wenzeslaus So, I am finally finished with testing on Windows – for a long time it seemed that the Integrated mode does not work even for Standalone or OSGeo4W – but I did not give up and was finally able to get it working at least for the Standalone variant. To sum it up (I plan to include these hints in the docs as well): Standalone installer I hoped that #6289 helped with including the notebook package to GRASS daily builds, but it seems that besides python3-jupyter also python3-notebook would need to be added. Therefore, after clicking on the Launch Jupyter Notebook button it fails with a Jupyter Notebook not installed error – we need to run from the Python GUI console: I also had multiple Jupyter installations on the machine, so originally used shutil.which("jupyter") executable proved unreliable (and also jupyter may be installed without jupyter notebook) – so it is safer to use the GRASS_PYTHON variable as the executable. I tested this on Linux as well and it works correctly, always picking the Jupyter notebook associated with GRASS. After that, the Jupyter Startup dialog opens with two options – launching Jupyter Notebook in the default browser or the integrated solution directly in GRASS GUI.
To make the Integrated mode functional, first, we need to check the current wx version: and then force-reinstall wxPython from pip (for example, for version 4.2.2): After that, the Integrated mode starts successfully. OSGeo4W installer Tested on the then-latest dev version of GRASS (fc1694e) by selecting the installation of "grass" package in Select packages dialog. The scripts for Jupyter notebook GUI support were then manually copied into the grass86 folder (similarly to the Standalone case). The setup is similar to the official Jupyter guide: https://grass-tutorials.osgeo.org/content/tutorials/get_started/JupyterOnWindows_OSGeo4W_Tutorial.html#set-up. The key difference is that during the Advanced install, in the Select packages dialog, the python3-notebook package should ideally be explicitly selected as it is not installed by default. If forgotten, it can be installed afterwards in the OSGeo4W shell with Here, the situation is as follows:
|
| python, | ||
| "-m", | ||
| "notebook", |
There was a problem hiding this comment.
This python -m notebook replaced earlier, jupyter notebook. Is that intentional? python -m jupyter notebook would be the equivalent command.
There was a problem hiding this comment.
Yep, it is actually intentional since I had problems with running python -m jupyter notebook for the Standalone installer. For some reason, I still ended up with this output:
C:\Users\karlovskal>"C:\Program Files\GRASS 8.5\extrabin\python3.exe" -m jupyter --version
Selected Jupyter core packages...
IPython : 9.12.0
ipykernel : 7.2.0
ipywidgets : 8.1.8
jupyter_client : 8.8.0
jupyter_core : 5.9.1
jupyter_server : 2.17.0
jupyterlab : 4.5.6
nbclient : 0.10.4
nbconvert : 7.17.1
nbformat : 5.10.4
notebook : 7.5.5
qtconsole : not installed
traitlets : 5.14.3
C:\Users\karlovskal>"C:\Program Files\GRASS 8.5\extrabin\python3.exe" -m jupyter notebook --version
Could not import runpy._run_module_as_main
Traceback (most recent call last):
File "<frozen importlib._bootstrap>", line 1371, in _find_and_load
File "<frozen importlib._bootstrap>", line 1342, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 938, in _load_unlocked
File "<frozen importlib._bootstrap>", line 1179, in exec_module
File "<frozen runpy>", line 14, in <module>
File "C:\Program Files\GRASS 8.5\Python312\Lib\importlib\__init__.py", line 57, in <module>
import warnings
File "C:\Program Files\GRASS [8.5\Python312\Lib\warnings.py"](http://8.0.0.5/Python312/Lib/warnings.py%22), line 591, in <module>
filterwarnings("default", category=DeprecationWarning,
File "C:\Program Files\GRASS [8.5\Python312\Lib\warnings.py"](http://8.0.0.5/Python312/Lib/warnings.py%22), line 155, in filterwarnings
import re
File "C:\Program Files\GRASS 8.5\Python312\Lib\re\__init__.py", line 125, in <module>
from . import _compiler, _parser
File "C:\Program Files\GRASS 8.5\Python312\Lib\re\_compiler.py", line 18, in <module>
assert _sre.MAGIC == MAGIC, "SRE module mismatch"
AssertionError: SRE module mismatch
C:\Users\karlovskal>"C:\Program Files\GRASS 8.5\extrabin\python3.exe" -m notebook --version
7.5.5
I also tried to explicitly install jupyter notebook using C:\Users\karlovskal>"C:\Program Files\GRASS 8.5\extrabin\python3.exe" -m pip install jupyter notebook and the result of above-pasted output was the same. Moreover, after the installation all requirements already satisfied (nothing added), so I have no idea where the problem is (probably some environment problem?)
Anyway, I came to the conclusion that using python -m notebook command is just safer for users.
Interestingly, for the OSGeo4W installer i did not get the same error:
C:\OSGeo4W>python -m jupyter --version
Selected Jupyter core packages...
IPython : 9.11.0
ipykernel : 7.2.0
ipywidgets : 8.1.8
jupyter_client : 8.8.0
jupyter_core : 5.9.1
jupyter_server : 2.17.0
jupyterlab : 4.5.6
nbclient : 0.10.4
nbconvert : 7.17.0
nbformat : 5.10.4
notebook : 7.5.5
qtconsole : not installed
traitlets : 5.14.3
C:\OSGeo4W>python -m jupyter notebook --version
7.5.5
C:\OSGeo4W>python -m notebook --version
7.5.5
See my comment. Is it about which command you are running? Do you need to run that particular command?
You can also install it for the user, e.g. with a dialog/button, if it is that simple. However, here it seems you switch from OSGeo4W packages to pip (even more relevant below for a OSGeo4W install).
Is it
I think it makes more sense to use |
…r.py (replaced by Path writability check)
@wenzeslaus I tested the wxpython pip reinstall also for OSGeo4W instalator and it works as well. So I made two dialogs - the first one installs the notebook if not available and the second one reinstalls wxpython from pip to ensure the webview2 edge runtime support. Tested on standalone as well as OSGeo4W and works great - integrated mode is functional after the restart.
Yep, changed! |
|
@wenzeslaus I created the video how last changes works for the fresh standalone installation (it would look the same for OSGeo4W). cil3.mp4 |
…tall from pip (to make integrated mode available)
lindakarlovska
force-pushed
the
new-jupyter-pane-in-gui
branch
from
8de9431 to
87534c3
Compare
7 participants
This pull request introduces the support for running Jupyter notebooks directly within the GUI.
How it works
There is a new Launch Jupyter Notebook Environment button added to the top menu, right next to the Launch Python Editor button (In this PR, these workflow-related buttons are now grouped together, since all of them serve a similar purpose — working with scripts or automation workflows.)
When you click the Launch Jupyter Notebook button, a new dialog appears — Start Jupyter.
In this dialog, you can:
The working directory is very important because in this directory the Jupyter server will be launched which means that each running Jupyter server is tied to a single directory — meaning that your entire Jupyter session is associated with that directory. If you want to work in a different directory, you simply start another Jupyter session from the GUI.
Besides the selection of a working directory, there’s also an option to create a preconfigured “welcome” notebook (a template). This lets you start working immediately with GRASS and Jupyter already initialized — including automatic imports of GRASS scripting and Jupyter modules, and initialization of the session to match your current GRASS environment.
Once you confirm the dialog:
• A local Jupyter server is started.
• The status bar (bottom left corner) shows information such as the running port and the server PID.
• If you selected the template option, a welcome.ipynb file is created in the chosen working directory, already set up with an initialized GRASS Jupyter session.
Why the Working Directory Matters
A Jupyter server always requires a working directory.
By default, GRASS uses <MAPSET_PATH>/notebooks, since it’s always available and writable. In the first version of this PR, the directory was created automatically inside the mapset.
During the PSC meeting in August 2025 ( https://grasswiki.osgeo.org/wiki/PSC_Meeting_2025-08-08), we decided it would be better to:
That’s why the new Start Jupyter dialog exists — it provides both of these options.
What if Jupyter Isn’t Available?
Two cases are handled:
In both cases, the Launch Jupyter Notebook button will be disabled.
If the user clicks it anyway, an explanatory message will be shown describing the issue.
Windows Support
In version 8.5, the “Launch Jupyter” button will be active only on UNIX systems.
To make it work on Windows (both OSGeo4W and the standalone installer), Jupyter needs to be included in the build process.
That’s not too difficult — Jupyter itself is already included in the standalone installer — but its dependencies (folium and ipyleaflet) are missing from OSGeo4W packages.
I’ve submitted a PR to add them (jef-n/OSGeo4W#36 ) but it’s still awaiting feedback.
Until this is resolved, Jupyter integration won’t be available on Windows in version 8.5.
Implementation Overview
python/grass/workflows/
- directory.py
Contains the JupyterDirectoryManager class, which manages Jupyter notebooks linked to the given working directory.
Responsibilities include mainly: Import/export of .ipynb files and managing notebook templates (welcome.ipynb, new.ipynb).
- server.py
Provides two key classes: JupyterServerInstance which handles the lifecycle of an individual Jupyter server instance—installation check, port management, startup, shutdown, URL generation, etc. Also handles cleanup using atexit and signal handling to ensure servers are terminated when GRASS exits via GUI, exit, CTRL+C, or kill PID. Further, JupyterServerRegistry—a singleton that registers all active Jupyter server instances. It allows the global shutdown of all running servers when GRASS is closed from the GUI.
- enviroment.py
High-level orchestrator JupyterEnvironment integrates a working directory manager (template creation and file discovery), a Jupyter server instance and a registration of running servers in a global server registry
- template_notebooks/
- welcome.ipynb: A welcome notebook created on demand if checked in the Start Jupyter dialog (created only if the working directory is empty – no .ipynb files present)
- new.ipynb: A template used when the user creates a new notebook via GUI
gui/wxpython/jupyter_notebook/
- panel.py - defines the JupyterPanel class, which creates the interactive panel inside the GUI. It includes: A toolbar and an AuiNotebook widget that lists and displays .ipynb files from the working directory
- notebook.py
Class JupyterAuiNotebook—Handles logic for adding AUI notebook tabs with JavaScript injection for hiding the Jupyter File menu and header.
- dialogs.py
Class StartJupyterDialog with Jupyter startup settings.
- toolbars.py
Class JupyterToolbar—Implements the toolbar controls for notebook actions: Create new notebook, Import notebook, Export notebook, Dock/Undock, Quit
Additional Notes
Following steps
For example:
These could become part of a grass.jupyter library.