Using Jupyter (IPython) Notebooks in Canopy

Using Jupyter notebooks in Canopy

As of Canopy 1.6.1 and higher (download latest version here) all Jupyter (IPython) notebooks are now opened automatically in your default web browser rather than within the Canopy GUI. These notebooks will continue to use Canopy Python and its packages.

This allows notebooks to take advantage of the latest Jupyter notebook functionality. When you use the Canopy GUI to create a new Jupyter notebook, or open an existing notebook, it is opened in your browser. These notebooks will be tracked in the Canopy File Browser's Recent Files list, but their contents will not be directly viewable within the Canopy GUI window.

When notebooks are opened from Windows Explorer, Mac Finder, or Enthought Training on Demand, Canopy is opened (if is not currently running), will track the notebook's usage, and will open the Jupyter notebook in a browser window.

You can use the Canopy Preferences' Notebook tab to customize the default directory where new notebook files will be saved. The starting default is the "Documents/Notebooks" subdirectory of your home directory. You can also specify whether you will be prompted for the directory and filename of each new notebook (by default, you will be prompted).

One difference between running Jupyter notebooks in the browser rather than the Canopy GUI (versions <=1.5.5) is that pylab mode is no longer enabled by default. Thus, when opening a notebook created in previous versions of Canopy, one must explicitly import and use the correct namespaces. Alternatively, running the Jupyter magic command %pylab at the beginning of the Jupyter notebook will enable pylab mode. Although using pylab mode will work and can be convenient for quick temporary work, it can also cause confusion and namespace pollution errors, so that it is good practice in most notebooks, to explicitly import all modules used. See "PyLab Mode".

A good alternative to the %pylab qt magic command is %matplotlib qt , which implements the interactive plotting of pylab mode without the potential for namespace pollution and confusion.

Updating from pre-Jupyter versions of Canopy

If you update Canopy from an earlier version, and do not completely reset / rebuild your Canopy User environment (see https://support.enthought.com/entries/23580651-Uninstalling-and-resetting-Canopy), then you must immediately update ipython in the Canopy Package Manager or using the enpkg command-line utility. Usually you will be prompted to do this the first time you start Canopy after updating.

Background

The Canopy GUI, up through version 1.5, provided a convenient interface to many IPython notebooks, especially useful for quick demos and experimentation. As a tradeoff for this integration, it had some limitations. The most fundamental was that notebooks saved by IPython version 3 and above could not be used in the Canopy GUI notebook. This is further described in "IPython: Installed version in the Package Manager is not being used in the Canopy GUI". There are also UI issues due to the platform on which the built-in notebook is displayed, and compatibility issues with some proxy firewalls.

Workaround for older versions of Canopy

If you are using a version of Canopy earlier than 1.6.1, and have problems with an IPython notebook in the Canopy GUI, we recommend that you close the notebook in the Canopy GUI, and instead open it manually in a browser. To do this:

1. In the Canopy Package Manager, update to the latest version of IPython.
2. From the Canopy Tools menu, open a Canopy Command Prompt (or Canopy Terminal) window.
3. At the command prompt (shell prompt), type: ipython notebook. This will open a full IPython Notebook in your default browser.
4. Navigate to your notebook and open it.  
5. You will have full access to all your Canopy packages.

Please be aware that any notebook that you create or save this way in a browser will not be readable in the Canopy GUI built-in notebook, for the reasons described above. However since the Canopy GUI notebook has been removed starting in version 1.6.1, this should not be a significant disadvantage.

Note about IPython version numbers

IPython software version number is not the same as Notebook format version number.
IPython version 2.x writes notebook format version 3 (and starting with 2.4.1 can read, but not write, notebook version 4).
IPython version 3.x and 4.x (Jupyter) write notebook format version 4. 

Known Issues

The first time that you open a notebook in a particular Canopy session, there may be a long delay while the browser is opened or wakened, the notebook server is started, and Jupyter is activated.

The browser window will not always pop into visibility on your screen after a notebook is opened, so you may need to switch tasks manually to bring it to the foreground.

If you rename a notebook in the browser, Canopy won't realize it and won't list the new name in the Recent Files list, but you can still open it from the file browser if you want, after which it will again appear in Recent Files.

Please do not enter support requests in article comments

Please use article comments for suggestions to improve the article. For individual support requests, please follow these guidelines.