norweeg / app_mode_jupyter_environment_and_shortcut

App Mode Jupyter Environment and Shortcut

Adds a shortcut for running JupyterLab in a Chromium-based browser's "app" mode (i.e. The application takes up the full browser window and has no browser UI e.g. the address bar, as if Jupyter Lab were a native application) for an existing environment with Jupyter Lab installed or creating one for you.

Requirements

• An conda-based installation of Anaconda, Miniconda or Miniforge. Miniforge is recommended.
• menuinst >= 2.0.0 must be installed in the base environment alongside conda or in whichever environment contains conda
• A Chromium-based browser
  • On Windows, Google Chrome, Brave, and Microsoft Edge are supported. Preference will be given to your default browser, if it appears to be a Chromium-based browser, or to the first one of these browsers found. Microsoft Edge is guaranteed to be installed on Windows 10+ and is a fall-back if no other supported browser is found.
  • On MacOS, Google Chrome, Microsoft Edge, Brave, and Chromium are preferred in that order.
  • On Linux, Google Chrome, Microsoft Edge, Brave, and Chromium are supported and preferred in that order. If flatpak is installed and one of these browsers is installed with Flatpak (recommended), it will be preferred over any snap-installed or package manager-installed versions of any of these browsers.

Setup

1. Clone or download this repository
2. From a terminal, activate your base conda environment (or whichever environment conda is installed in)
3. Run python ./setup_jupyter.py your_jupyter_env_name_here

Remove Shortcut

To remove the shortcut created by this script, run python ./setup_jupyter.py --remove your_jupyter_env_name_here

FAQ

1. Why don't you support Mozilla Firefox or Safari?

   To my knowledge, neither have an "app-mode" like Chromium-based browsers do. When/if they ever do, they will be supported.

2. Why am I being prompted for admin permissions?

   By default, menuinst tries to install/remove the shortcut from a system-level location. You can safely cancel/ignore that prompt(s) (it may prompt you multiple times) which will cause menuinst to fallback to a user-specific location instead. Unfortunately, there does not seem to be a way to have menuinst prefer to install/remove shortcuts for the current user rather than system-wide.

3. What about other Chromium-based browsers?

   I added support for what I perceived to be the most popular Chromium-based browsers that I am familiar with in order of my perception of their popularity. There's just so many of them and it seems like there's always new ones being released! Feel free to open a pull-request to add additional browsers.

4. What about dev/canary builds of the browsers?

   Supporting the dev/canary builds of every browser on every platform would greatly increase the complexity of this code for marginal gains. You should not be using those as your everyday browser and you probably have a stable version of that same browser installed anyway.

5. Why is support for MacOS so buggy?

   The last MacBook that I owned was a 2013 MacBook Air which now runs Linux. While I have attempted to support MacOS as best I can, I am working from my own recollection of using conda-based Python on MacOS combined with whatever I could find on google regarding the MacOS icon format and executing browsers from the CLI. I am not able to actually test this code on MacOS. I welcome any bug reports (and, hopefully, a pull-request for a fix) for any bugs, especially ones affecting MacOS.

6. What about my existing JupyterLab configuration?

   The jupyter_lab_config.py used by the shortcut only sets values for ServerApp.root_dir and ServerApp.browser. If you have a custom ~/.jupyter/jupyter_lab_config.py file, its contents are executed at the end of the shortcut's jupyter_lab_config.py, adding to or overriding any configuration values set by by it.

7. What is nb_conda_kernels and why does this script want to install it in my Jupyter environment.

   nb_conda_kernels allows JupyterLab to run kernels in any installed conda environment which has a Jupyter kernel (e.g. ipykernel for Python) installed in it without having to install Jupyter and all its dependencies into that conda environment. It allows you to have a single version of JupyterLab installed in a single, purpose-made environment so you are not maintaining multiple JupyterLab versions or configurations.

8. How should I update my Jupyter environment?

   That's up to you. I will periodically run conda update -n jupyter --all && conda update -n jupyter python to update everything in my Jupyter environment (named jupyter).