ArcGIS Notebooks in ArcGIS Pro
ArcGIS Notebooks are now integrated into ArcGIS Pro with the 2.5 release. ArcGIS Notebooks use open-source Jupyter notebook, which has been included in the ArcGIS Pro Python distribution since ArcGIS Pro 2.1. As of the ArcGIS Enterprise 10.7, ArcGIS Notebooks were also integrated into the ArcGIS Enterprise Portal with Notebook Server.
Jupyter notebooks combine cells of live Python code with narrative text and visualizations in a single document. They have become widely adopted by the data science community because they support iteratively and interactively documenting, processing, analyzing, and visualizing data in a notebook format that can be saved, shared, and used to report results.
If you would like to learn more, here are some additional resources with further details:
- Notebooks in Pro Documentation
- How to create and add Python notebooks in ArcGIS Pro 2.5 Blog
- Five Tips To Get You Started With Jupyter Notebooks Blog
- Using Jupyter Notebooks from within ArcGIS Pro environment Blog
Check out the tutorial sections below to get started or skip ahead to the Q&A section. Feel free to leave a comment if you have any questions or feedback.
1. To get started with notebooks in Pro, open a new project and from the Insert ribbon click New Notebook.
2. After saving the notebook, open it using the Catalog pane.
3. You can arrange the notebook view so that you can see your map and notebook side-by-side.
If you'd like to see an example of how ArcGIS Notebooks and ArcGIS Pro interact, follow along with this quick tutorial as we explore the 2010 census population data for New England states. Alternatively, you may download the sample project package.
4. Make sure you are signed into ArcGIS Online or your organizational Portal, then navigate to the Portal tab on the Catalog pane, click the Living Atlas tab and search "USA States". Context-click the item named "USA States (Generalized)" and select Add To Current Map.
5. We are interested in the population of US states, so let's also open a chart. Context-click the USA_States_Generalized layer in contents and choose Create Chart > Bar Chart.
6. On the Chart Properties pane, under Category or Date, choose the Name field from the dropdown. Under Numeric field(s) check POP2010 on. Leave everything else on default and click Apply.
7. You can arrange the chart, map, and notebook views so they are all visible.
8. In the Notebook view, enter the following text into the first cell.
### New England Population and Area
What are the 2010 population and area of New England?
9. Select Markdown from the dropdown list above the cell, and then press shift+enter on the keyboard to run the current cell and simultaneously create a new cell below (or select the next cell).
The cell will be formatted in markdown and the entered text becomes a header and description for your notebook. This allows you to narrate the notebook and break it into sections.
10. From the Map ribbon click the Select button and select the states Maine, Massachusetts, New Hampshire, Rhode Island, and Vermont. These states are commonly referred to as New England. Note that the states are also selected in the chart.
11. Geoprocessing operations performed in the notebook will also honor selections made in Pro. Complete steps 12-14 with the New England states still selected.
12. Enter the following code into the next cell of your notebook and press shift+enter to run it.
# Set data
lyr = "USA_States_Generalized"
13. In the next cell, enter the following code and from the Cell menu of the notebook view select Run Cells And Select Below.
with arcpy.da.SearchCursor(lyr, ["POP2010", "SHAPE@"]) as rows:
ne_pop = 0
geoms = arcpy.Array()
for row in rows:
ne_pop += row
ne_geom = arcpy.Polygon(geoms)
14. In the next cell below, enter the following code and press control+enter, this will run the cell without creating a new cell below.
With this tutorial, you have seen how you can use ArcGIS Notebooks interactively in ArcGIS Pro by bringing 2010 State Census data into your map, exploring population attributes with a chart, and then referring to the data by layer name in your notebook and operating on a selected subset of the data to obtain a summary of the total population and area of New England states. You can also use the arcgis library to analyze data using a pandas-based spatially enabled data frame.
Questions & Answers
Q: How does the experience of running an ArcGIS Notebook in Pro differ from running a Jupyter Notebook outside of Pro?
A: With notebooks running in Pro, you can open a map view and a notebook view side-by-side, allowing you to visualize and directly interact with the emerging data, document and automate the workflow, and save it for later.
- Layers and other contents of your map can be accessed in your notebook by name. You can access data that is not currently in your table of contents using the full path to the data. Note that dragging and dropping an item from the contents pane into the notebook is currently not supported.
- If you have selected data in the map view, geoprocessing tools running from the notebook honor the selections.
- Global geoprocessing environment settings are respected and can be overridden by environment settings set from the notebook.
- The output of geoprocessing tools is added to the active map by default.
- When a notebook view is active, the Notebook ribbon will appear. From here, you can create a new notebook, save the current notebook, or interrupt the kernel.
- The result of running a geoprocessing tool from the notebook will be logged in the geoprocessing history.
- Geoprocessing workflows can occur during an ongoing editing session. If a geoprocessing tool directly modifies a feature being edited in an edit session (it does not save the result of geoprocessing as another feature class), you can save or discard the modifications from the Edit ribbon.
An edit session can be started by directly editing the target layer within ArcGIS Pro using the Edit ribbon, or by using arcpy.da.Editor(<workspace>) as illustrated in the following lines of code:
infc = "tl_2010_us_state10"
workspace = r"path/to/data.gdb"
with arcpy.da.Editor(workspace) as edit:
result = arcpy.management.DeleteFeautres(infc)
Q: Can I use the standard Jupyter Notebook keyboard shortcuts?
A: Keyboard shortcuts work just like they do in the default web based Jupyter Notebook.
Q: Why can't I use magic (%) or shell (!) commands in my notebook?
A: Magic and shell commands are not currently supported when running a notebook in Pro.
Q: Why are figures from matplotlib not showing up in the cell output of my notebook?
A: Inline visualizations from matplotlib are not currently supported. You will need to use the show() method to view these. For example:
import matplotlib.pyplot as plt
import pandas as pd
sedf = pd.DataFrame.spatial.from_featureclass("tl_2010_us_state10")
Q: I cannot find the option for restarting the kernel.
A: You currently cannot restart the kernel unless you close and reopen ArcGIS Pro. You can, however, interrupt the kernel using the "Interrupt Kernel" button from the Notebook ribbon.
Q: I'd like to use R or C# in my notebook instead of Python.
A: You can only open a Python kernel in notebooks running in ArcGIS Pro, other languages are not supported.
Q: I'd like to export my notebook (.ipynb) as a python script (.py), is that possible?
A: Yes, you can use the jupyter command nbconvert from the command prompt:
jupyter nbconvert --to script "Path\To\Your_Notebook.ipynb"
The resulting Your_Notebook.py file will be in the same directory as Your_Notebook.ipynb.
Q: Can I open a Jupyter notebook in ArcGIS Pro that I have previously created outside of Pro?
A: Yes, ArcGIS Notebooks are simply Jupyter notebooks and any .ipynb file can run in Pro, however, it is your responsibility to ensure any libraries used in these other environments are available in the active environment of ArcGIS Pro. To open an existing notebook in Pro, navigate to the folder containing the notebook(s) using the Catalog pane and either double-click to open it or context-click the notebook and choose Open Notebook.
Q: Can I use my ArcGIS Notebook created in Pro across other platforms?
A: ArcGIS Notebooks are simply Jupyter Notebooks (.ipynb) and can be run in any Jupyter environment or as hosted ArcGIS Notebooks in ArcGIS Enterprise or ArcGIS Online (currently in beta). However, it is your responsibility to make sure that any libraries used in the notebook are available in these other environments.
- Using Notebooks hosted on Enterprise Portal in ArcGIS Pro: There are several options for moving a hosted notebook to your local machine.
- Make sure you are signed in to a portal. From the Catalog pane in ArcGIS Pro, go to Portal > My Content, context-click a notebook item (if present), and select Download.
- Signed into Portal on the web browser. From the Notebook Editor in Portal, on notebook menu ribbon, click File, then Download as and choose notebook (.ipynb).
- Signed into Portal on the web browser. From the notebook's Item Details page (accessible from the Content tab by clicking on a notebook item), click Download to download the notebook in .ipynb format.
- Using Notebooks created in Pro on my Enterprise Portal:
- You can upload any notebook file (.ipynb) to your portal. To do this, sign into your organization's Portal from the browser, go to the Content tab of the contents page, click Add Item > From your computer and choose From my computer. From the Add an item from my computer dialog, click Choose File and browse to a notebook file on your computer, provide a title and tags, and then click Add Item.
Q: From an ArcGIS Notebook hosted on portal I can authenticate my credentials using arcgis.GIS("home") instead of entering my username and password, why doesn't this work from my notebook in Pro?
A: If you are connected to your ArcGIS Online organization or Enterprise Deployment in your current ArcGIS Pro session, you can use arcgis.GIS("pro") instead. See the documentation on working with different authentication schemes for more details.