Skip to content


William Stein edited this page Dec 12, 2017 · 23 revisions

Jupyter Notebooks on CoCalc

Remember: if you don't find what you need, or if you'd like to ask a question, then please email at any time. We'd love to hear from you! Please include a link (the URL address in your browser) to any relevant project or document, as part of your email.

Two Ways of Using Jupyter Processes:

CoCalc lets you use back-end Jupyter processes, or kernels, such as the languages Python and R, from both Jupyter notebooks and Sage worksheets.

Note: Running Jupyter kernels from a Sage Worksheet is also known as "the Sage worksheet Jupyter bridge."

List of Questions:

Question: I want to use a Jupyter notebook (with Sage support)

Click "+New", then enter a filename and click Jupyter Notebook. This is a complete rewrite from scratch of the classical Jupyter notebook for CoCalc, but enhanced with realtime synchronization that supports multiple simultaneous editors, a TimeTravel slider that lets you browse everything you have done in the notebook, and much much more.

It is possible to switch to the classic Jupyter client any time you have a notebook open. Click the button labeled "Classic Notebook..." just to the right of "TimeTravel" in the notebook. The notebook will be displayed using the classic Jupyter client. Similarly, in the classic Jupyter client, there is a button "Modern Notebook..." at the right end of the toolbar allowing you to switch to the new client. The Modern/Classic Notebook setting will apply to other notebooks in your project as well. More details....

It is also possible to run a standard Jupyter notebook server (no sync, not integrated into the cloud) by going to project settings and clicking on the link labeled "Plain Jupyter Server". Collaborators on your project can securely use the Jupyter notebook server by visiting this link, but nobody else can.

If you want to make a Jupyter notebook that supports Sage, select the SageMath kernel (in the menu, select Kernel --> Change kernel). This will import the Sage library and enable the preparser.

Question: I want to use my own copy of Jupyter, which is part of my own Python stack

You can install any version of Python you want into your own project -- just download and build it locally, and install Jupyter (and whatever you want) into it. Then, make a directory "bin" in the home directory of your project and put a symlink to your ipython there, e.g.,

cd ~/bin/
ln -s /path/to/your/ipython .

In project settings, restart your project server (just to be sure), then make sure that when you type "ipython" on the command line, you get your Jupyter. Then clicking on existing Jupyter notebooks or creating new ones (through the graphical user interface) should use your copy of Jupyter. It just uses the "Jupyter" that is in the path, since ipython-notebook just sets up some options and runs "ipython notebook." (Look at ~/.smc/ipython-notebook .)

Question: I want to install the cite2c Jupyter extension, so I can use Zotero


Note: Due to some unfriendly users launching attacks from CoCalc, you must pay to enable internet access from within your project in order to access online resources like GitHub.

Do the following in a terminal:

git clone && cd cite2c && sage

Now when you open a Jupyter notebook, there will be two new buttons at the end of the button bar, which will let you insert citations.

Question: How do I use Asymptote for vector graphics in a Jupyter notebook?


You can copy the file at this link Examples of drawing scientific diagrams with Asymptote in IPython notebook into your CoCalc project and run it.


  1. You may get the message, UserWarning: %install_ext is deprecated on installing the IPython magic extension in the first cell. You can still run the rest of the notebook.
  2. To avoid freeglut (asy): failed to open display '' error when calling show(), add file config.asy to the directory with the notebook, with these two lines:
import settings;

Question: How can I install Jupyter's nbextensions configurator?


You can install it in your own project. For that, you need internet access enabled or somehow upload the code into your project. Then, install it like this in a terminal (create a new file terminal.term)

 pip install --user --no-deps jupyter_nbextensions_configurator
 jupyter nbextensions_configurator enable --user

and restart the Jupyter server in CoCalc

smc-jupyter restart

Then, in order to see the configurator, you have to open an ipynb file. Click on the the "About" button in the top right click on the link there to open the version of jupyter without the synchronization. There, either go to the main page or the one dedicated for the nbextensions. The URL looks like this:<your_project_id>/port/jupyter/nbextensions

Question: How can I customize the default Jupyter kernel or template?

Overall, your default kernel will be whatever kernel you last explicitly selected.

You can also create templates for files in a given project to customize how your initial Jupyter notebooks all look (and what kernel they use) in a given project. Just make a file ~/templates/linux/default.ipynb. For example, do this in a terminal:

cd; mkdir -p templates/linux/; open templates/linux

then create a file default.ipynb. Set the kernel to anything you want, and save the file.
Now any jupyter notebook you create will have that kernel. Of course, you can further customize this file however you want. The same templates work for any file type, by the way.


Question: How do I start a Jupyter kernel in a Sage Worksheet

For a quick reminder, sample code is available for opening an Anaconda3 session. In the Sage worksheet toolbar, select Modes > Jupyter bridge.

Use the jupyter command to launch any installed Jupyter kernel from a Sage worksheet

py3 = jupyter("python3")

After that, any cell that begins with %py3 will send statements to the Python3 kernel that you just started. If you want to draw graphics, there is no need to call %matplotlib inline.


import numpy as np; import pylab as plt
x = np.linspace(0, 3*np.pi, 500)
plt.plot(x, np.sin(x**2))

You can set the default mode to be your Jupyter kernel for all cells in the worksheet: after putting the following in a cell, click the "restart" button, and you have an anaconda worksheet.

anaconda3 = jupyter('anaconda3')
%default_mode anaconda3

Each call to jupyter() launches its own Jupyter kernel, so you can have more than one instance of the same kernel type in the same worksheet session.

p1 = jupyter('python3')
p2 = jupyter('python3')
p1('a = 5')
p2('a = 10')
p1('print(a)')   # prints 5
p2('print(a)')   # prints 10

Question: What kernel features are supported in Sage worksheets?

The features listed below are demonstrated in sample worksheets at

  1. Help, with list of available kernels: jupyter?.
  2. Execution count: [n]: 'XYZ'.
  3. pwd
  4. ls with color-coded output
  5. Plot to png.
  6. Plot to image/svg+xml.
  7. Display image from local file or URL.
  8. Ignore python prompt markers.
  9. Error output with ansi colors.
  10. Non-blocking output.
  11. Function docstring with ansi colors.
  12. Long docstring and magic output to scrolling div.
  13. Markdown, including inline and display MathJAX.
  14. Embed Youtube video.
  15. Embed web page from external site.
  16. LaTeX output from Math() and Latex() objects.
  17. Play audio from local file.
  18. Play audio from generated data.
  19. Autocompletion, if supported by jupyter kernel - tested with Python, R, and bash.

Question: How Can I get help on running a Jupyter kernel from a Sage worksheet?

You can get a version of this help message from within a Sage worksheet, regardless of default mode, with


Question: Are there any known issues with running a Jupyter kernel from a Sage worksheet?

  1. Raw input hangs the worksheet: a = raw_input("type here: ").
  2. If default_mode is enabled for the jupyter mode and a cell starts with a jupyter magic command, the cell needs to start with a comment or mode decorator, or the jupyter magic will be interpreted as a sagews mode.
  3. Long docstring and magic create scrollable div, but there is no close button.
  4. If the jupyter kernel crashes, it must be restarted manually.
  5. %load somefile - hangs the .sagews
  6. Embedded youtube widget is rendered multiple times.
  7. ipywidgets are not supported.
  8. jupyter? calls _get_doc() three times

Question: Which Jupyter kernels are pre-installed?

From any Sage worksheet cell, just type the following to get a full and up-to-date listing.


Question: How can I add my own Jupyter kernel?

See for instructions.

Question: I want XXX, but I don't see XXX above.

Do not hesitate to email THE LINK TO YOUR PROJECT to or!forum/sage-cloud


Clone this wiki locally
You can’t perform that action at this time.