How to share Jupyter/Colab ML projects that actually run

You finally get your notebook working. You send it to a friend, guide, or recruiter… and they reply with:

• ModuleNotFoundError: No module named ...
• FileNotFoundError: ./data/train.csv not found
• “Run all gives a different result than what you showed.”

Sharing ML work as “here’s my notebook” almost never works cleanly. The environment, data paths, and run instructions are all locked in your head.

In this article, we’ll walk through what breaks when you share notebooks, how to improve things with a few simple practices, and how NoteCapsule can help you ship ML projects that people can actually run.

Why your notebook breaks on other machines

Most broken shares come down to four issues:

• Missing or different dependencies. Your machine has scikit-learn==1.2, theirs has nothing or a different version.
• Data paths that only make sense on your setup. Hard-coded paths like "C:\\Users\\you\\Downloads\\data.csv" or "/content/drive/MyDrive/something".
• Hidden state. You ran cells in a different order; variables exist for you but not on a clean run.
• No instructions. The other person has no idea what they’re supposed to run, in what order, or what the expected outcome is.

Baseline: make your notebook more shareable

Before bringing in any tools, a few simple habits will dramatically improve shareability:

1. Use relative paths inside the project

Instead of:

data = pd.read_csv("C:/Users/me/Desktop/dataset/train.csv")

Prefer:

data = pd.read_csv("./data/train.csv")

And keep a project structure like:

project/
  notebook.ipynb
  data/
    train.csv
    test.csv

2. Capture dependencies in a file

At minimum, run:

pip freeze > requirements.txt

Or for Colab, list what you explicitly installed:

!pip install pandas scikit-learn matplotlib

3. Add a tiny “README” section at the top

Even inside the notebook, start with a markdown cell that answers:

• What is this project?
• What data does it expect, and where?
• How do I run it from scratch?

Going further with NoteCapsule Capsules

NoteCapsule sits on top of that baseline and helps you package everything into a reusable project snapshot – a Capsule.

Each Capsule includes:

• the notebook file,
• a generated requirements_suggested.txt from your imports,
• a data_manifest.json listing files & folders you use,
• a README_template.md you can quickly fill in.

!pip install notebookcapsule -q

from notebookcapsule import create_capsule

create_capsule(
    name="kaggle_titanic_baseline",
    data_dirs=["./data"]
)

This creates a self-contained folder under ./capsules/ that you can zip and send:

capsules/
  2025-11-24_kaggle_titanic_baseline/
    notebook.ipynb
    requirements_suggested.txt
    data_manifest.json
    README_template.md
    capsule_meta.json

What it’s like for the person receiving your Capsule

Imagine you’re sending this to your guide or a recruiter. They would:

1. Unzip the Capsule into a folder on their machine.
2. Create a virtual environment (optional but good practice).
3. Install dependencies from requirements_suggested.txt (plus any manual tweaks).
4. Make sure the data files listed in data_manifest.json exist in the expected ./data/ folders.
5. Open notebook.ipynb and run it from top to bottom.

They’re not guessing where the data lives or which libraries to install – it’s all in the Capsule.

Using Capsules with Google Colab

If you’re primarily on Colab, a practical flow is:

1. Mount Drive in your Colab notebook.
2. Keep your project under a single Drive folder (not scattered paths).
3. Use create_capsule(...) with data_dirs pointing to your project’s data folders.
4. Export the Capsule with export_capsule("name") if you want a zip file.

from notebookcapsule import export_capsule

export_capsule("kaggle_titanic_baseline")
# → capsule_kaggle_titanic_baseline_2025-11-24.zip

You can then share that zip via Drive or email. The recipient can work locally or in their own Colab environment.

Summary: from “here’s my notebook” to “here’s my project”

• Don’t just send a raw notebook and hope it runs.
• Use relative paths, a data/ folder, and a basic requirements.txt as your baseline.
• Add NoteCapsule Capsules to capture notebook + environment hints + data layout + README.
• Send the Capsule folder or zip when you want someone to actually experience your project, not just scroll cells.