ArcGIS Notebooks in ArcGIS Pro (3.0) FAQ
ArcGIS Notebooks are based on the open-source Jupyter notebook, which has been included in the ArcGIS Pro Python distribution since ArcGIS Pro 2.1. Since Pro 2.5, notebooks can run directly in ArcGIS Pro allowing a side-by-side view of your map and notebook and for direct interactions with the data on your map. 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. See the ArcGIS Notebooks landing page to learn more about notebooks across Esri products.
To learn more about notebooks in Pro, see these links:
Frequently Asked Questions
Q: When opening a notebook in ArcGIS Pro, why did I receive a "Failed to load notebook" error?
A: This is a known issue caused by a recently upgraded Notebook stack on the Esri channel. We have made a hotfix available, to install it simply search for and install the pro-notebook-hotfix package from the Package Manager in ArcGIS Pro. This can be accomplished with the following steps
- Open ArcGIS Pro and navigate to the Package Manager.
- Open the Environment Manager (click the gear icon
near the top right).
- Activate your clone.
- Click the refresh button (
).
- Close the Environment Manager.
- Click the Add Packages tab.
- Search for pro-notebook-hotfix and install the package.
Alternatively, you can run the following command from the Python Command Prompt to install the hotfix into the active environment:
conda install pro-notebook-hotfix
Notebooks should now open.
If there are still issues, the problem may be something else. Please check if you have made any changes to the Jupyter configuration file jupyter_notebook_config.py, make sure you haven't modified the c.NotebookApp.ip or c.NotebookApp.port configuration options, as modifying these will prevent ArcGIS Pro from launching the notebook.
Q: How does the experience of running an ArcGIS Notebook in ArcGIS Pro compare with running a Jupyter Notebook outside of Pro?
A: With notebooks in ArcGIS Pro, you can open a map view and a notebook view side-by-side, allowing you to visualize and directly interact with the data.
- 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 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. Note that the Map view must be active in order for the Edit ribbon to be accessible.
Q: Can I use the standard Jupyter Notebook keyboard shortcuts?
A: Keyboard shortcuts work just like they do in Jupyter Notebook.
At 3.0, we have intentionally disabled the print, browse forward, and browse backward shortcuts, and enabled the zoom and find shortcuts.
Additionally, the command palette is currently not brought up with the keyboard CTRL + SHIFT + p keys when in Edit mode. To open the command palette, escape to Command mode and press p. There are plans to bring this back in line with the standard Jupyter Notebook experience.
Q: Using keyboard shortcuts to undo code, the latest actions I performed in the map are instead undone. Using copy and paste to move code results in similarly strange behaviors.
A: This is a known and unfortunate bug. To immediately work around this issue, make sure the notebook pane of the notebook you are editing is the active one (click on the tab), and confirm the Notebook ribbon is displayed. This should get Pro back into a state where keyboard shortcuts are performed on your notebook, and not on the map.
Q: Can I use magic ( % ) and shell ( ! ) commands in my notebook?
A: Yes! Many magic and shell commands are supported since ArcGIS Pro 2.6. Magic and shell commands are a convenience that enhance data analysis and offer a bridge for executing shell commands without leaving your notebook. Certain magic and shell commands are unsupported, including but not limited to %history, !ipconfig, and !ping.
For more information regarding magic and shell commands, see magic commands and shell commands.
Q: Why are figures from matplotlib not showing up in the cell output of my notebook?
A: Inline visualizations from matplotlib are supported since ArcGIS Pro 2.6. You will need to use the matplotlib.pyplot.show method to view these. For example:
%matplotlib inline
# Imports
import matplotlib.pyplot as plt
import pandas as pd
import arcgis
# Create spatially enabled data frame (SEDF)
sedf = pd.DataFrame.spatial.from_featureclass("USA_States_Generalized")
# Create plot
plt.bar(sedf.STATE_NAME, sedf.POP2010)
# Update plot elements
plt.suptitle("Population of New England States", fontsize=16)
plt.ylabel("Population (in millions)")
plt.xticks(rotation=45)
# Draw the plot
plt.show()Q: Where can I 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 on the Notebook ribbon. While not a complete workaround, you can also use the %reset -f magic command to clear all variables in the namespace.
Q: Can I 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) to a Python script (.py), is that possible?
A: Yes, you can export a notebook to a Python (.py) or HTML (.html) file from the Notebook ribbon’s Export button.
you can also use the Jupyter command nbconvert from the command prompt, or you can run the command directly from your notebook by preceding the command with an exclamation mark (!).
!jupyter nbconvert --to script "Path\To\Your_Notebook.ipynb"
The resulting Your_Notebook.py file will be in the same directory as your notebook, 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 notebook can be run in ArcGIS Pro. However, it is your responsibility to ensure any libraries used in these other environments are available in the active environment of ArcGIS Pro.
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. 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 into a portal. From the Catalog pane in ArcGIS Pro, go to Portal > My Content, right-click a notebook item, and select Download.
- Signed into Portal on the web browser. From the Notebook Editor in Portal, on notebook menu ribbon, click File> Download as > 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. 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.
- You can upload any notebook file (.ipynb) to your portal. 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: The Cell menu is missing from my notebook.. why?
A: This can occur when Jupyter Notebook runs out of allocated memory. Try clearing all cell outputs (you will need to use the Command Palette since the Cell menu is missing):
- Enter command mode (selected notebook cell is blue).
- Press the p key to bring up the Command Palette.
- Type "clear all cells output" and press enter.
You may need to reload the notebook.
To prevent this from happening, try to minimize large cell outputs. For example, if a DataFrame is very large and you don't need to view all records in the table, use df.head(x) to display only the first x records.
You can also try increasing the memory limit.
- Generate the Jupyter configuration file jupyter_notebook_config.py using the Python Command Prompt.
jupyter notebook --generate-config - Open the jupyter_notebook_config.py (it should be in %userprofile%\.jupyter), and edit the following property (replace <your limit> with your desired memory limit):NotebookApp.max_buffer_size = <your limit>
Q: Can I open a notebook in Pro from a UNC path?
A: With ArcGIS Pro 3.0, you are now able to open a notebook in Pro from a UNC path - just be careful about collisions as this opens up the possibility of multiple users editing the same file. If you are still on an earlier version of ArcGIS Pro and need to use notebooks from a UNC path, we recommend upgrading to 3.0. Otherwise, the best workaround is mapping the UNC path to a drive or alternatively creating a symbolic link.
Q: I keep clobbering variables when I have multiple notebooks open in Pro. Why are variable names being shared across multiple notebooks?
A: ArcGIS Pro runs a single Python instance. This execution context is shared by each notebook opened in a single instance of ArcGIS Pro. Depending on the contents of concurrently open notebooks, this could potentially result in variable name collisions. To avoid potential issues you may consider:
- Using unique variable names across all concurrently running notebooks
- Running the %reset -f magic command as needed to delete all the variables in the namespace
Q: Why are the environment variables I set in Notebooks (or Python Window) not being honored by Geoprocessing tools I run from the Geoprocessing pane?
A: This behavior is due to the environment levels hierarchy.
When setting an environment variable using arcpy.env, you are setting it at the Script level. Since this is the lowest level in the hierarchy, the setting will not be honored at any of the above levels. In order for your environment variables to be honored by both Script and Geoprocessing tools, you must set the environment variables using the Application settings from your project.
