Jupyter Notebooks

CoCalc offers several options for hosting running Jupyter Notebooks online.

What’s a Jupyter Notebook?

A Jupyter notebook is a specific filetype with the ending .ipynb, which records an interactive session with a Kernel. It made up of cells, which can either store one or more lines of code or formatted text. When you run a cell – which evaluates the piece of code in the cell via the active kernel session – you can see its output after the calculation is done. This combination of communicating back and forth with a kernel and adding descriptive text makes this form of document very attractive.

Jupyter Kernels

You can choose the programming language and environment by selecting a Jupyter kernel for the notebook. Popular choices are Python3, SageMath, and R. There many others. Our page on Jupyter Kernel Selection shows how to set the kernel.


Make sure and double-check that you’re working with a suitable kernel for your calculations!

CoCalc Jupyter Notebook Basic Features

By default, a Jupyter notebook on CoCalc has all CoCalc’s core features, including real-time collaboration, side chat, and TimeTravel. Read more in our blogpost. The basic user interface looks like the following:


Above the main area is a menu bar and a button row:

  • The menu bar contains all commands, and in particular the Kernel menu is for changing it if necessary.
  • The button row gives you a one-click access to Run the current cell (otherwise press your Shift+Return keys), a way to restart the kernel (which clears the current session) and a Save button to make sure CoCalc has stored the file. The Time Travel button allows you to see previous versions of that notebook, such that you can go back in time to recover from a bad change.
  • Active cell: in the screenshot above, the blue bar on the left and a blue border around a cell indicates that this is the currently active one. Actions like Run, Delete Cell, etc. operate on the currently selected cell. It is also possible to select more than one cell.
  • Execution counter: On the left of each cell, there is an execution counter In [ x ]. The number x increases each time a cell is being run. After the kernel stopped and restarted, that counter starts again at 1.
  • The output of code cells is below the input cell. For example, Out [7]: is the output of cell In [7]:. In the right hand corner of the input cell is some information about how long it took to calculate the result.
  • Text cells are slightly different. Select “Markdown” in the [ Code ] dropdown menu in the button bar to change a code cell to such a markdown text cell. There, you can use Markdown to format the text. Similar to code-cells, either Run these text cells to see the processed Markdown code or press Shift+Return. To edit a text cell, either double click it or press your Return key.
  • Saving: more general, the nice things about Jupyter Notebooks is that they save all your intput and output in one single file. This means you can download or publish the notebook as it is, and everyone else sees it in exactly the same way.

CoCalc Jupyter Notebook Enhancements

These enhanced features are available in CoCalc Jupyter notebooks:

  • drag-and-drop: You can drag and drop images into markdown cells:

    1. If you have a markdown cell and are not actively editing it, there is an image icon/button on the far right of the cell. Just click that and you can then select an image from your computer. It’ll be uploaded and inserted into the cell.


    Click image icon to open a drop zone for image placement

    2. If you have a markdown cell and are editing it, select “Edit –> Insert image in selected markdown cell…” from the menu and proceed as above.

    3. The markdown editor in Jupyter doesn’t yet support direct drag-and-drop and copy/paste of images, but it probably will soon. See https://github.com/sagemathinc/cocalc/issues/4762

  • cell numbers: Cells are numbered consecutively at upper right. Unlike execution numbers shown in brackets at left, these don’t change when you re-run a compute cell or go blank when you clear output, and markdown cells are numbered as well as code cells.
  • run time for compute cells: When a compute cell is executed, the amount of time it takes is displayed at upper right. See preceding figure.
  • table of contents: Table of contents level (indicated by font size) is the same as markdown heading level, i.e. “#” for top level, “##” for second level, etc. Click the “Contents” button in the “Notebook” menu at the top of a notebook, or select “File –> Table of Contents”, or split the frame and change one of the resulting frames to “Table of Contents”. Each entry in the table of contents is a clickable link that takes you to the corresponding cell in the notebook.
  • slideshow CoCalc notebooks offer you a shortcut for making a slideshow. Select “View” > “Cell Toolbar…” > “Slideshow” to add a Slide button above the right of each cell. For each cell, you can specify whether it is a slide, subslide, or fragment. To view the slideshow, click the “Slideshow” in the “Notebook” menu at the top of a notebook, or select “File” > “Slideshow”, or split the frame and change one of the resulting frames to “Slideshow”. The latter allows you to view the original notebook side-by-side with the slides.

enabling “Slide” button in cell toolbar


selecting slide type for each cell

When presenting, the next slide is to the right, while the next subslide is below. Fragments are revealed within the present slide. Click in the slideshow and then click “?” to see a list of keyboard shortcuts. If you modify the notebook, you can update the slideshow by clicking in the toolbar above the show and clicking “Build”, or by clicking “File” in the toolbar above the notebook and again selecting “Slideshow”.


original notebook side by side with slideshow

Note: the legacy method of creating and presenting a slideshow by using a separate Linux terminal command and starting a small web server is still available by clicking “File” > “Slideshow via nbconvert…”.

  • nbgrader integration: CoCalc offers nbgrader support without adding separate Jupyter extensions. This ehancement is in under active development. See nbgrader in CoCalc for more information.

Jupyter Widgets

Jupyter Widgets are Python objects that let you build interactive GUIs for your Jupyter notebooks. CoCalc Jupyter notebooks combine the interactive capabilities of Jupyter widgets with the usual advanced features of the CoCalc platform, including real-time collaboration, TimeTravel, and side chat.

A good way to get started using Jupyter widgets is to go through the Widget List in the main widgets documentation.


CoCalc Jupyter notebook with Jupyter Widgets

Classical versus CoCalc

If you are having trouble with the CoCalc Jupyter Notebook, you can switch to the Classical Jupyter Notebook. You can always switch back to CoCalc Jupyter easily later (and please let us know what is missing so we can add it!).

NOTE: The Classical Jupyter notebook is not supported in the Firefox browser. See Jupyter Server options below if you need to use Firefox and do not want to use the CoCalc Jupyter notebook.

You can change the default for opening a Jupyter notebook - CoCalc or Classical - by clicking the checkbox labeled “Jupyter classic …” in your Editor settings in Account Preferences.

To switch your notebook to Classical from within a CoCalc Jupyter notebook: select “File” → “Switch to Classical Notebook” in the menu.


switching to Classical from CoCalc Jupyter notebook

To switch your notebook to CoCalc from within a Classical Jupyter notebook: select “File” → “Switch to Classical Notebook” in the menu.


switching to CoCalc from Classical Jupyter notebook

The main reasons to use the classical notebook are:
  • need for certain extensions (Howto setup Jupyter Extensions).
  • interactive widget support Note: as of April, 2019, CoCalc Jupyter notebooks support ipywidgets.

See our list of Jupyter related issues for more details.

Collaboration with Classical Jupyter

Here’s a pro tip if you need a classical Jupyter notebook for one of the reasons above and want real-time collaboration as well. If you and another user both select “Jupyter classic” in Account / Preferences / Editor, then open the ipynb file in cocalc as you normally would, multiple users are supported.

Multiple users are NOT supported with the Plain Jupyter Classic Server and JupyterLab Server activated under Project settings. Multiple users ARE supported with classical Jupyter embedded as a normal editor within CoCalc, which is what you get when you enable “Jupyter classic” as in the preceding paragraph.

Basically, we fully implemented two very different approaches to realtime collaboration for Jupyter.

Don’t mix CoCalc and Classical!


Multiple people simultaneously editing the same notebook, with some using classical and some using the new mode, will NOT work! Switching back and forth will cause problems (you may need to use TimeTravel to recover). Please avoid using classical notebook mode if you possibly can!

Alternatives: Plain Jupyter Server and JupyterLab Server

You can also run the full classical Jupyter notebook server, using either Plain Jupyter Server or JupyterHub Server. These options are available under Project settings and (+) New.

Using either of these options for the classical notebook has an advantage: it does not affect your “Jupyter classic” Editor setting, allowing you to keep CoCalc Jupyter notebook as the default for opening .ipynb files in the CoCalc main interface.

Note that the same warning applies as above: you shouldn’t open the same ipynb file in cocalc and in classical/lab servers.

Tips and Tricks

Use the Halt Button to Conserve Memory

Each running Jupyter Notebook spawns a session in your project. This uses up memory, which could cause troubles running all your processes in your project.

You can either restart the kernel to clean up its current memory (i.e. all variables are deleted), or if you’ve finished working on that notebook, click the Halt button to stop the kernel and close the notebook.


Remove Local Files to Troubleshoot a Notebook

If you have a Jupyter notebook that suddenly stops working, especially with extensions or widgets, you can try removing local files in a Linux Terminal, then restarting and running the notebook:

rm -rf .sage .ipython/ .config/ .local/ .jupyter .cache/

You will need to reinstall packages you added locally after doing the above.

Play a .wav file in a Jupyter notebook

CoCalc Jupyter notebooks now support embedding audio files. There are several ways you can embed an audio file so it plays nicely in a Jupyter notebook:

wav file on disk

  1. Create a file on disk, e.g., tuba.wav. If you’re using simpleaudio or something else to create sound, make sure to figure out how to save that sound to a local file.

  2. Put this in the markdown cell and hit shift+enter:

    <audio controls=true src="tuba.wav"/>
  3. You’ll see an embedded audio controller appear and you can play your audio.


audio controls to play wav file

wav file embedded in notebook

Alternatively, you might want the file to be embedded in the notebook itself. To do this, click the picture icon on the right of a markdown cell, or click “Edit –> Insert images in …”, then drag and drop to copy the wav file as an attachment to that cell. Then replace the image attachment code that is generated by:

<audio controls=true src="attachment:tuba.wav"/>

and again you’ll see a player and can play your file.

Notebook too large? Remove output.


Jupyter notebook file too large error

If the size of your notebook exceeds 50 MB, you will not be able to open it in the usual way; instead, you will see the error message shown above. Usually, the problem occurs when the notebook has created large amounts of output. In that case, there is a command you can run from the Linux Terminal to remove output. If removing output results in a small enough notebook, you will be able to open the “-no-output” version of the notebook normally.

# run this from a CoCalc Linux terminal (.term file)
# use the actual name of your notebook for "myfile.ipynb"
cc-jupyter-no-output myfile.ipynb
# the above command creates myfile-no-output.ipynb

If your Jupyter notebook is creating an image file from a plot that exceeds the size limit, here are some things you can do:

  1. If you are using a CoCalc Jupyter notebook (which we generally recommend), it may be possible to open the notebook with the classical jupyter server or JupyterLab. Once you have the file open, you can modify the code to produce a smaller plot. Then you can go back to using the CoCalc notebook.

  2. Revert the notebook to an earlier version, before the large plot was created. Click the Backups button in the file listing and copy over an earlier version, then modify your code to produce a smaller plot.

  3. The default image file format for plots with the “R (R Project)” Jupyter kernel is SVG. For large plots, smaller files may be produced if the format is set to PNG, because SVG plots (the default) grow in size proportionally to the data they are supposed to show, wherease PNG plots are rasterized, so file size does not have the same proportionality relationship to amount of data. To set image output format in an R Jupyter notebook to PNG, run the following in a compute cell before creating the plot:

    options(jupyter.plot_mimetypes = c('text/plain', 'image/png'))