Move a Jupyter or Colab notebook into CoCalc

Move an ordinary .ipynb notebook from local Jupyter or Colab into a CoCalc project, restore its inputs and Python environment, and check a fresh execution. This is a file-and-environment migration; source-platform services are not converted automatically.

Prepare the source files

1. Save the notebook in the source application and download its .ipynb file. Also download the datasets and local modules it reads. Keep their relative directory structure. Do not rely on outputs already embedded in the notebook.
2. Record the Python version and required packages. If the source environment has a reproducible dependency file, include it. Review notebook cells for absolute paths, credentials, cloud mounts, and platform-specific APIs.
3. For a small practice migration, download analysis.ipynb, analyze.py, and measurements.csv from the research example directory. Use each file's raw download, not an HTML copy of its GitHub page. This example uses only the Python standard library for analysis.

Upload into one project folder

Open a project you can edit. In full CoCalc, open Files, create and open a new research-workflow folder, then upload the three practice files there. For nested real datasets, preserve subdirectories; uploading only the notebook does not transfer their contents. See Project files and SSH, SCP, and rsync for transfer choices.

Open analysis.ipynb in the full notebook editor and use Kernel -> Change Kernel... to select a local Python 3 kernel. The saved kernelspec from another computer may name an environment that is not installed in this project. Selecting a matching language does not install the original packages.

For this first migration, choose a kernel running inside the project. Remote SSH kernels are a separate option: project uploads do not synchronize to their remote filesystem.

Check the interpreter and files

The practice notebook's first cell checks its working directory and required files. In your own notebook, run an equivalent preflight:

import sys
from pathlib import Path
print(sys.version)
print(sys.executable)
print(Path.cwd())
assert Path("measurements.csv").is_file(), "Place the CSV beside this notebook"

Check that the path is the intended project folder. Prefer paths relative to the notebook's working folder over laptop-specific paths. For a more complex layout, record where execution starts and use explicit paths to the data.

Recreate missing packages

The practice analysis needs no additional packages. For other notebooks, follow Create a custom kernel to create an isolated Python environment, install ipykernel and the needed packages, and register it. Select that kernel, restart it after package changes, and rerun the preflight.

Do not conclude that installation worked for the notebook merely because an import succeeds in a separate terminal. Compare sys.executable in the notebook with the Python used to install packages. Pin versions when the source notebook requires them and record any compatibility changes you make.

Distinguish a missing kernel from a missing package

If R, SageMath, or another language is absent from the selector, inspect the project runtime image first. Images provide different software; the notebook file does not bring its original kernel along. In a project terminal, inspect the registered kernels:

jupyter kernelspec list

Use the displayed kernelspec locations to identify a user registration that may shadow a system kernel. Inspect before changing it; do not delete all user Jupyter configuration to fix one notebook. If the command itself is unavailable, record that error and check the selected environment. For R, R --version in the project terminal independently checks the terminal executable, not the notebook registration. After changing an image or registration, reopen the kernel selector, choose the intended kernel, and rerun the notebook preflight.

A missing shell command is another layer: command -v python3 and python3 -m pip --version identify the terminal's interpreter and pip location. Compare them with the notebook's sys.executable. An importable package does not necessarily install a shell command with the same name, or add it to PATH.

Replace source-platform assumptions

Run from a fresh kernel and inspect the artifact

Restart the kernel to clear old variables, then run every cell from top to bottom. For the practice notebook, confirm:

count=4 mean=5.0
Saved result matches the computation

The notebook asserts the count and mean, saves notebook-result.json, and reads it back. Open that file from Files. It should contain count 4, mean 5.0, and an input SHA-256 hash. Save the notebook, close and reopen it, and confirm that its code and saved outputs are present.

For your real notebook, define equivalent checks before accepting the migration: expected table dimensions, representative values, plots, and exported files. A notebook can finish executing while one or more cells contain errors. Inspect the outputs, not just whether a run command returned.

Download the resulting notebook and JSON if you need a local copy. Test a fresh project rerun with Reproduce an analysis, and leave a handoff note containing the source, environment, run order, checked output, and unresolved differences.

Troubleshoot the first rerun

• Unknown kernel: choose or register an installed kernel; copying a kernelspec name does not copy its interpreter.
• ModuleNotFoundError: check the active interpreter before reinstalling.
• FileNotFoundError: check paths, uploaded subfolders, and local versus remote kernel location.
• Kernel terminated: use Kernel troubleshooting and start with a smaller dataset; repeated full reruns can repeat the same memory failure.
• Different result: compare the input bytes, package versions, cell execution order, and random seeds. Preserve the original notebook while investigating.