ArcGIS Developers
Dashboard

ArcGIS API for Python

Using the JupyterLab Environment

JupyterLab is a modern interactive development environment (IDE) that allows you to work with code, data, and the Jupyter notebook format. Starting with v1.5.0, the ArcGIS API for Python can be used in JupyterLab for a truly powerful development experience.



JupyterLab builds upon all of the major components of the classic Jupyter Notebook experience (notebooks, terminal, text editor, file browser, ipywidgets, etc.) to create a flexible and powerful user experience. Click here or here to read more about JupyterLab.

Getting Started

Installation

  1. Install the latest ArcGIS API for Python in a new conda environment. Activate that environment.
  2. Install jupyterlab in your conda environment via conda install jupyterlab=2
    • Note: you will need a 2.X version of JupyterLab, and at least version 1.8.2 of the ArcGIS API for Python for this to work.
    • Versions 1.5 -> 1.8.1 work in JupyterLab 1.X, but have different installation instructions.
  3. You will need to have nodejs installed on your computer to install widget extensions. Visit get npm, or install in conda via conda install nodejs.
    • Make sure you have the latest compatible version of nodejs installed (14.6 at the time of writing this guide, but can change in the future)
  4. Run jupyter lab to launch a new jupyterlab instance.
  1. When jupyter lab is first launched, you will need to enable extensions. Press the jigsaw puzzle piece, and "Enable" to enable instructions.
  1. Install the @jupyter-widgets/jupyterlab-manager extension by searching for it and pressing "Install".
  1. Install the arcgis-map-ipywidget extension by searching for it and pressing "Install".
    • NOTE: your installed ArcGIS API for Python version must EXACTLY match this installed arcgis-map-ipywidget npm jupyterlab extension, or else it will not work. (ex. 1.8.2 of the Python API installed, 1.8.2 of the arcgis-map-ipywidget extension installed. jupyter labextension list will show you all versions of extensions installed)
  1. Rebuild Jupyter Lab by pressing "Rebuild":
    • If this rebuild fails in the UI, run jupyter lab build from your OS's command line to rebuild all extensions manually. You also may need to restart your jupyter lab instance.
  1. When prompted, reload the page.

All extensions should be properly loaded for you to use the ArcGIS API for Python with JupyterLab! Let's get started with some basics:

File Explorer

Just like the classic Jupyter Notebook experience, JupyterLab offers a file explorer to open existing notebooks, create new notebooks, and organize your content. JupyterLab's file explorer is on the left pane of the main view.



JupyterLab interacts with the same .ipynb notebook format. The only difference is the user interface, and the additions of some other external extensions.

Using Windows and Tabs

You may notice that Jupyter has a concept of 'windows' and 'tabs', unlike the classic Jupyter Notebook experience. This is a very powerful feature of JupyterLab: you can stack notebooks, place notebooks side by side, organize notebooks by tabs, etc. Simply click and drag any 'tab' as seen below:



Any window can be dragged like this. JupyterLab lets you view and edit file types such as .csv, .json, etc. in new windows, as seen above.

Using Cell Utilities

Similar to the windows and tabs above, JupyterLab allows users to move cells in a notebook by dragging and dropping them. JupyterLab also supports dragging cells from one notebook to another notebook. Simply click the area to the left of the cell you want to move, and drag it wherever:



JupyterLab also lets you select multiple cells by holding the Shift key. You can move these cells as mentioned before, or right click and select 'Copy Cells' to copy them. JupyterLab has many options in their right click context menu worth exploring, including the 'Create New View For Output' option. This allows you to take any cell output and duplicate it in a new window, allowing you to stack it, view it side-by-side, etc.



There are other cool things you can do with cells in JupyterLab not described in this guide, keep on exploring!

Integration with the Map Widget

v1.5.0 of the ArcGIS API for Python introduces many new exciting features for the Map Widget, including 2D rotation, 3D mode, 3D renderer support, and more. You can read this guide page for more information about these other features of the new widget: this guide will highlight the map widget's seamless JupyterLab integration.



The MapView class's default view behavior is the same as in the classic Jupyter Notebook environment: the widget is displayed it in a cell's output area. However, you may notice a new UI button that is only visible in a JupyterLab environment:

By pressing this button, your widget will move from your cell's output area into a new window. This window can be tabbed, split, etc. like all other windows. If you want to restore the widget to the notebook it originated from, press this button:

Try this for yourself! If you're reading this guide in a JupyterLab setting, run the below cell:

In [3]:
from arcgis.gis import GIS

#Create a map widget like you have done many times before
gis = GIS()
map1 = gis.map()
map1
Out[3]:

WebMaps and WebScenes

WebMap and WebScene Objects include this same UI button: run the two below cells to try for yourself!

In [1]:
from arcgis.mapping import WebMap
webmap_item = gis.content.get("ab42b088573d4253a22a8b38ee698ccd")
webmap = WebMap(webmap_item)
webmap
Out[1]:
In [2]:
from arcgis.mapping import WebScene
webscene_item = gis.content.get("421433baeb8d487b903d4a89df79149b")
webscene = WebScene(webscene_item)
webscene
Out[2]: