wxGUI: Initial support for Jupyter-based workflows#5901
wxGUI: Initial support for Jupyter-based workflows#5901lindakarlovska wants to merge 28 commits intoOSGeo:mainfrom
Conversation
be55385 to
817795e
Compare
|
Just set up the discussion page for the notebook working directory topic and workflows topic in general: #5909. |
3a3b7e7 to
55974d3
Compare
968784b to
9d30c42
Compare
65e8ea7 to
08a1f06
Compare
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: |
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? |
python/grass/workflows/server.py
Outdated
| if sys.platform.startswith("win"): | ||
| # For now, always disabled on Windows | ||
| return False |
There was a problem hiding this comment.
Why not to do the full test and just see what is there instead of assuming what is the situation? Does Windows produce some user-visible error when subprocess fails?
There was a problem hiding this comment.
Just note for me - leaving this for the end of testing - test it also on Windows.
python/grass/workflows/server.py
Outdated
| proc = subprocess.Popen( | ||
| [ | ||
| "jupyter", | ||
| "notebook", |
There was a problem hiding this comment.
I don't know why Bandit does not complain here, but anyway, using shutil.which to get the full path and then executing that would help running this on Windows. Is this code running for you on Windows?
|
So, I noticed it was leaving zombies behind, so I had Claude analyze server.py and it identified the issue and also couple other issues, here is the AI-rewritten code, I tested it and I am fairly confident about Claude getting it right. the other file describes the reasons behind the changes. |
| class JupyterStartDialog(wx.Dialog): | ||
| """Dialog for selecting Jupyter startup options.""" |
There was a problem hiding this comment.
This is a basically a starter of jupyter notebook --no-browser with JupyterServerInstance being the controller for it. So, it seems it wouldn't be difficult to add a button here to start jupyter notebook with browser or jupyter lab. This would help users get the full Jupyter Notebook or Jupyter Lab experience without running these from the command line. Button in the GUI dialog:
Cancel | Open Notebook in Browser | Open Lab in Browser | Open Integrated Notebook
For Open Notebook in Browser and Open Lab in Browser, the notebook tab shows only controls for the shutting down the server. Open Integrated Notebook is the current experience.
This may align well with something like a Run RStudio button. We already do things to make running RStudio easier from within a GRASS session on Windows (see grass/mswindows), but in this case, we don't do anything for it in GUI (unlike Python scripts and now Jupyter notebooks).
There was a problem hiding this comment.
Notably, this would be still available even when the user does not have wx.html2.
There was a problem hiding this comment.
That's a great suggestion, I like it!!
| content = template_copy.read_text(encoding="utf-8") | ||
|
|
||
| # Replace the placeholder '${NOTEBOOK_DIR}' with actual working directory path | ||
| content = content.replace( |
There was a problem hiding this comment.
I would also hardcode the mapset path in gj.init:
env = gs.gisenv()
mapset_path = Path(env["GISDBASE"]) / env["LOCATION_NAME"] / env["MAPSET"]
content = content.replace(
"${NOTEBOOK_MAPSET}", f"\\\"{mapset_path}\\\""
)That way when you switch mapset in GUI and restart kernel in notebook, you will still init the same mapset session. Otherwise the behavior can be strange when you switch mapsets, restart kernel and then run session of the current mapset in a file saved in a different mapset.
| self.dir_picker = wx.DirPickerCtrl( | ||
| self, | ||
| message=_("Choose a working directory"), | ||
| style=wx.DIRP_USE_TEXTCTRL | wx.DIRP_DIR_MUST_EXIST, |
There was a problem hiding this comment.
Why wx.DIRP_DIR_MUST_EXIST? I don't see why you shouldn't be able to create a new directory.
| webview = event.GetEventObject() | ||
| js = """ | ||
| var interval = setInterval(function() { | ||
| // --- Jupyter Notebook 7+ (new UI) --- | ||
| var topPanel = document.getElementById('top-panel-wrapper'); | ||
| var menuPanel = document.getElementById('menu-panel-wrapper'); | ||
| if (topPanel) topPanel.style.display = 'none'; | ||
| if (menuPanel) menuPanel.style.display = 'none'; | ||
|
|
||
| // --- Jupyter Notebook 6 and older (classic UI) --- | ||
| var headerContainer = document.getElementById('header-container'); | ||
| var menubar = document.getElementById('menubar'); | ||
| if (headerContainer) headerContainer.style.display = 'none'; | ||
| if (menubar) menubar.style.display = 'none'; | ||
|
|
||
| // --- Stop once everything is hidden --- | ||
| if ((topPanel || headerContainer) && (menuPanel || menubar)) { | ||
| clearInterval(interval); | ||
| } | ||
| }, 500); | ||
| """ | ||
| webview.RunScript(js) |
There was a problem hiding this comment.
I suggest discussing this with Copilot or something. At least max tries would be nice.
| - Jupyter Notebook 6 and older (classic interface) | ||
| - Jupyter Notebook 7+ (Jupyter Lab interface) | ||
|
|
||
| This is called once the WebView has fully loaded the Jupyter page. |
There was a problem hiding this comment.
Yes, but then the code uses interval to run the code, so this text should probably reflect that, possibly only before the JS code block , like "...but Jupyter UI may be (is?) create(ing?) the elements dynamically afterwards, so we need to wait for them to appear."
| webview = event.GetEventObject() | ||
| js = """ | ||
| var interval = setInterval(function() { | ||
| // --- Jupyter Notebook 7+ (new UI) --- |
There was a problem hiding this comment.
We don't want the --- ... --- comment graphic elsewhere, so let's not add that here.
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
Co-authored-by: Anna Petrasova <kratochanna@gmail.com>
943102a to
9461909
Compare
Thanks for the review @petrasovaa and @wenzeslaus! |
@wenzeslaus Could you please leave a positive review on jef-n/OSGeo4W#36? I was hoping it could be merged, but it hasn’t been yet. If I understand correctly, you’re suggesting that we shouldn’t specifically handle folium and ipyleaflet for our use case, and that users who need them can install them separately on Windows. Would merging this OSGeo4W PR therefore resolve the Windows-related issue? |
…tive, deletation of availability check - will be done after clicking on new buttons in Start dialog
…ve workflows together
017ff58 to
6825d39
Compare
…d some other refinements
…n Windows - not tested yet
What I'm saying that there is no difference between Folium and Jupyter as missing dependencies as both can be installed with pip, so if user can install one, it can install the other. On the other hand, folium and ipyleaflet may need to be always installed with pip and they may need to be the latest version. Hard to tell for me.
What I did not understand was the test for jupyter executable present on Windows, or rather the the assumption that it is never there. |

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.