Use Jupyter notebooks

What Jupyter in CoCalc is for

CoCalc runs standard Jupyter notebooks inside a durable project workspace. The notebook file is collaborative and the kernel runs in the project backend. Execution and output capture can continue after a browser disconnect while the project and kernel remain running.

Use notebooks for exploratory computation, teaching, data analysis, reports, plots, and workflows where code, output, and explanation belong together.

Start working

1. Open a project.
2. Create or open an .ipynb file.
3. Choose a kernel.
4. Run cells, edit markdown, and save work as usual.

For the creation flow, see Create a Jupyter notebook.

Open a legacy Sage worksheet

In a project where you can edit files, opening analysis.sagews normally opens analysis.ipynb in the same folder. CoCalc creates the notebook if that path is missing or empty and leaves the original worksheet in place.

If a nonempty analysis.ipynb already exists, CoCalc opens it without reconverting or comparing it with the worksheet. To try a fresh conversion without replacing that notebook, copy the worksheet to a new basename whose .ipynb path does not exist, then open the copied worksheet.

Before rerunning the notebook:

1. Keep the original .sagews file, including its historical outputs, for comparison. Converted code cells start with empty outputs and no execution count; saved worksheet results are not copied into the new notebook.
2. Review the converted cells. A cell beginning with %md becomes Markdown; other input becomes code, with surrounding whitespace trimmed. Check hidden input/output settings, which are not reliably preserved across all cells.
3. Choose an available, compatible SageMath kernel. Conversion sets the notebook kernel metadata to sage / SageMath; it does not install SageMath, packages, or the worksheet's original environment. Check required input files and dependencies before running cells.
4. Rerun the cells you have reviewed and compare their results with the original worksheet. Legacy magics, interactive behavior, and external dependencies may need adaptation; conversion does not execute or validate the computations.

What CoCalc adds

CoCalc notebooks are designed for shared and long-running work:

1. Multiple people can edit the same notebook in realtime.
2. Cells can keep running after a browser disconnect while the project and kernel remain running.
3. Output is captured server-side and shown when you reconnect.
4. TimeTravel records detailed notebook history.
5. Large notebooks and large outputs are handled with CoCalc-specific rendering.
6. Side chat, agents, terminals, and project files live next to the notebook.

A configured browser-idle policy can stop a hosted project even while a cell runs. Before leaving work unattended, check Project host lifecycle actions in your site's Docs index. A project or kernel stop loses in-memory variables; inspect saved files and outputs before rerunning work. See kernel recovery.

Keep complete results when output is limited

Select an available, compatible kernel before running a notebook. A Python interpreter in the terminal does not by itself establish that a Python kernel is installed and registered. If the selector has no usable kernel, see Custom Jupyter kernels.

A run can limit the output initially displayed in the notebook. When available, Fetch additional output... retrieves more output retained by the backend. That output can become unavailable; a saved or read-only view may not offer the same retrieval control. Many printed lines can be combined into fewer output messages, so the number of visible lines is not a reliable completeness check.

For research results, have the calculation write the complete table, array, or other artifact to a file. Record its actual location and validate its expected records and scientific results. A remote kernel may write on another machine; transfer the file into the project before looking for it in Files. Save the notebook as well: the live notebook, its saved .ipynb file, and a separately written result are different artifacts.

Download the result through Files and check the downloaded copy. Comparing hashes verifies matching bytes, not scientific correctness. Retain the inputs, code, environment information, and result together. A truncated display does not prove that the result file is incomplete, and a successful-looking preview does not prove that it is complete.

Choose a notebook view

A notebook frame can use the classic cell-oriented layout or the content-first Studio view, which puts outputs and prose in the main column and adds a mini table of contents, a minimap, and a reading mode that hides code. Switch between them at any time on the same live notebook; see The Studio notebook view.

Kernels and environments

Use the kernel selector to switch between available project kernels. If you need a project-specific Python environment, create a custom kernel backed by a virtual environment; see Custom Jupyter kernels with uv.

For a shared software stack across many projects, use a runtime image instead of hand-configuring each notebook.

On CoCalc AI, you can also run a notebook's kernel on an SSH-accessible machine, including a GPU VM, while keeping the notebook in your project. See Remote Jupyter kernels on CoCalc AI. Remote files are not automatically synchronized with project files.

Agents and notebooks

Agents should treat the live notebook state as the source of truth. Use cocalc project jupyter or the browser-session notebook APIs for durable notebook inspection and execution instead of editing .ipynb JSON directly.

Agent dialogs use Recent agent sessions when available to choose where a request goes. With Automatically submit to Agent unchecked, send the prepared draft from the agent chat. The steps below identify the controls for each cell action.

Use Agent on a code cell

When AI tools are allowed in the project and the notebook is editable, open the Agent dropdown on a code cell. In Studio, hover over the code column to reveal the cell controls.

Choose one action: Ask for a question, Explain for a walkthrough, Fix Bugs, Modify, or Improve for changes, Document for code documentation, or Translate for another programming language.

1. Enter a question for Ask or instructions for Modify. For Fix Bugs, Improve, and Document, an optional note can focus the request.
2. For Translate, check the target programming language. Choosing this action does not itself switch the notebook kernel.
3. Check Recent agent sessions when shown, then choose Send. If Automatically submit to Agent is unchecked, send the prepared draft from the agent chat. Follow the request there and review the result.

The request identifies the notebook, cell ID, and kernel. It instructs the agent to read that cell and its outputs from the live notebook. The agent can inspect surrounding cells when needed. State constraints such as preserving the function signature or avoiding package changes in your request.

Improve a Markdown cell with Agent

An editable Markdown cell has its own Agent dropdown when project policy allows AI tools. Use it for the explanatory text and mathematics that accompany a computation.

Choose one action: Ask for a question, Document for an explanation, Proofread to improve the writing, Add Formulas for mathematical content, or Translate for another language.

1. Enter a question for Ask, or optionally describe what Document should emphasize. For Translate, check the Target language field.
2. Check Recent agent sessions when shown, then choose Send. If Automatically submit to Agent is unchecked, send the prepared draft from the agent chat. Follow the request there and review the result.

The agent is directed to the selected cell in the live notebook. After it responds, inspect the rendered Markdown and any changed mathematics. For a specific requirement, use Ask or the optional Document instructions; for example, request an explanation suitable for readers encountering the method for the first time.

Send a notebook error to Agent

When Fix with Agent appears with a notebook error, use it to start a repair request from that failure.

1. Click Fix with Agent beside the error output.
2. In the dialog, check Recent agent sessions when shown and select the conversation that should receive the request.
3. Click Fix with Agent in the dialog to submit it.
4. Follow the investigation in the agent chat. Review any reported verification and rerun the affected cell if needed.

The request includes the notebook path, the cell ID when available, the traceback, the cell input, and the kernel language when available. Long traceback and input text can be shortened. The agent is instructed to inspect the live notebook, investigate the cause, and apply a fix when possible; it can read current cell content and outputs instead of relying solely on the attached error text.

This shortcut submits a repair request. Include additional constraints or corrections in the agent conversation if the failure needs more context.

Troubleshooting

If a kernel stops, restarts, or the project runs out of memory, check the resource indicators and restart only the affected kernel when possible. For memory-specific failures, see Troubleshoot project memory.