OSGeo
wxGUI: Initial support for Jupyter-based workflows
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:
- Choose whether to use the default working directory (created automatically in your current MAPSET as <MAPSET>/notebooks), or
- Select a custom directory where you have write access.
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:
- Let users choose the working directory, and
- Offer a simple way to start with a good default template notebook.
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:
- Jupyter isn’t installed at all, or
- The user is on Windows, where Jupyter isn’t yet integrated in the GRASS build.
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 (https://github.com/jef-n/OSGeo4W/pull/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
- Multiple Jupyter servers can run in a single GRASS session (one per panel)
- All servers are automatically stopped when the GUI is closed or the session ends, even forcefully
- Newly created notebooks (welcome.ipynb or new.ipynb) are pre-initialized with the GRASS Jupyter environment and required imports for immediate use. Welcome.ipynb has some extra info about a working directory.
Following steps
- Enable Jupyter support on Windows once dependencies are available in OSGeo4W.
- At some point, we should revisit the discussion about implementing a GRASS-specific Jupyter kernel — I still believe it makes sense (for example, ArcGIS Pro also provides its own). With such a kernel, users could run notebooks without need for manual initialization code. They could simply select the GRASS kernel and start working in the same way, no matter whether launching Jupyter from within the GUI or in a standalone browser session. Just noting this here for context — we’ve already talked about it briefly, but during the summit in May 2025, it felt too early to make a decision. Perhaps it still is (@petrasovaa, @landa, @wenzeslaus).
- Having in mind that we aim to make Jupyter more accessible to users by enabling GUI integration, in the future, we could also consider introducing GRASS magic commands (IPython extensions) to make command-line operations easier in Jupyter. For example:
%region save=myregion – Save region
%mapinfo elevation - Print info about a raster or vector map
%info – Print info about current session
%run r.slope.aspect elevation=elevation slope=slope aspect=aspect
These could become part of a grass.jupyter library.
Just set up the discussion page for the notebook working directory topic and workflows topic in general: https://github.com/OSGeo/grass/discussions/5909.
Small note:
Under Gentoo GNU/Linux distribution I get error message when I hit Start Jupyter Notebook tool button:
ebook.py", line 21, in <module>
import wx.html2 as html # wx.html2 is available in
wxPython 4.0 and later
^^^^^^^^^^^^^^^^^^^^^^^
File "/usr/lib/python3.13/site-packages/wx/html2.py", line
15, in <module>
from ._html2 import *
ModuleNotFoundError: No module named 'wx._html2'
The above exception was the direct cause of the following
exception:
Traceback (most recent call last):
File
"/usr/lib64/grass85/gui/wxpython/main_window/frame.py", line
911, in OnJupyterNotebook
from jupyter_notebook.panel import JupyterPanel
File
"/usr/lib64/grass85/gui/wxpython/jupyter_notebook/panel.py",
line 24, in <module>
from .notebook import JupyterAuiNotebook
File "/usr/lib64/grass85/gui/wxpython/jupyter_notebook/not
ebook.py", line 23, in <module>
raise RuntimeError(_("wx.html2 is required for Jupyter
integration.")) from e
RuntimeError: wx.html2 is required for Jupyter integration.
I have install wxPython 4.x.x version:
GRASS world_latlong_wgs84/PERMANENT:~ > python -c "import wx;print(wx.version())"
4.2.3 gtk3 (phoenix) wxWidgets 3.2.8
wxPython import wx.html2 module is not available because wxPython and underlaying wxGTK library are not compiled with USE webkit flag. With enabled this flag module is available.
x11-libs/wxGTK library USE flags:
tomas@gentoo-gnu-linux:~$ equery u x11-libs/wxGTK
[ Legend : U - final flag setting for installation]
[ : I - package is installed with flag ]
[ Colors : set, unset ]
* Found these USE flags for x11-libs/wxGTK-3.2.8.1-r2:
U I
+ + X : Add support for X11
- - abi_x86_32 : 32-bit (x86) libraries
- - curl : Add support for client-side URL transfer library
+ + debug : Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
- - doc : Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
+ + gstreamer : Enable the wxMediaCtrl class for playing audio and video through gstreamer.
- - keyring : Enable support for freedesktop.org Secret Service API password store
+ + libnotify : Enable desktop notification support
+ + lzma : Support for LZMA compression algorithm
+ + opengl : Add support for OpenGL (3D graphics)
+ + sdl : Use Simple Directmedia Layer (media-libs/libsdl) for audio.
+ + spell : Add dictionary support
- - test : Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
+ + tiff : Add support for the TIFF image format
- - wayland : Enable dev-libs/wayland backend
+ + webkit : Add support for the WebKit HTML rendering/layout engine
dev-python/wxpython library USE flags:
tomas@gentoo-gnu-linux:~$ equery u dev-python/wxpython
[ Legend : U - final flag setting for installation]
[ : I - package is installed with flag ]
[ Colors : set, unset ]
* Found these USE flags for dev-python/wxpython-4.2.3-r2:
U I
- - debug : Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
- - python_targets_python3_11 : Build with Python 3.11
- - python_targets_python3_12 : Build with Python 3.12
+ + python_targets_python3_13 : Build with Python 3.13
- - test : Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
+ + webkit : Add support for the WebKit HTML rendering/layout engine
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