Understanding `.ipynb_checkpoints`: What they are and how to manage them

TL;DR

• Jupyter creates a hidden folder named .ipynb_checkpoints next to your notebooks.
• Inside it are snapshot files like MyNotebook-checkpoint.ipynb that let you revert to a prior state.
• They’re safe to delete, but you’ll lose the quick local rollback for that notebook.
• Add them to .gitignore, .dockerignore, and clean them in CI to avoid repo bloat.

What is .ipynb_checkpoints?

When you open and save a Jupyter Notebook, Jupyter keeps lightweight snapshots (checkpoints) of your work. These are stored in a hidden directory named .ipynb_checkpoints in the same folder as your notebook(s).

A typical structure looks like this:

project/
├─ data/
├─ analysis/
│  ├─ exploration.ipynb
│  ├─ model.ipynb
│  └─ .ipynb_checkpoints/
│     ├─ exploration-checkpoint.ipynb
│     └─ model-checkpoint.ipynb
└─ README.md

Each *-checkpoint.ipynb is a JSON notebook file, just like your main .ipynb, but captured at a previous point in time.

Are checkpoints the same as autosave?

Not exactly.

• Autosave updates your main .ipynb file at an interval (and on explicit save).
• Checkpoints are separate snapshots saved in .ipynb_checkpoints that you can revert to from the UI.

Front‑end behavior varies slightly:

• Classic Notebook exposes “Save and Checkpoint” and “Revert to Checkpoint.”
• JupyterLab provides “Revert Notebook to Checkpoint” in the File menu and keeps autosave configurable.
• Some alternative front‑ends (e.g., VS Code’s Jupyter integration) may not create .ipynb_checkpoints but will happily open notebooks that have them.

Why do they keep reappearing?

Because they’re part of Jupyter’s safety net. Even if you delete the folder, Jupyter will recreate it the next time it saves a checkpoint for that directory. That’s by design.

Is it safe to delete them?

Yes. Deleting .ipynb_checkpoints does not remove your main notebook; it only removes the snapshots. You’ll lose the quick “revert” option for those notebooks until new checkpoints are created.

Good times to delete:

• Before publishing or sharing a project archive.
• During CI or image builds to reduce size/noise.
• When a checkpoint captured sensitive output you don’t want distributed.

Keep them out of Git (and friends)

Checkpoints don’t belong in version control—Git already provides version history. Add these rules to your ignore files:

.gitignore

# Jupyter Notebook checkpoints
.ipynb_checkpoints/
**/.ipynb_checkpoints/
*-checkpoint.ipynb

.dockerignore

.ipynb_checkpoints/
**/.ipynb_checkpoints/
*-checkpoint.ipynb

The double‑star ensures nested directories are covered. The file pattern is a belt‑and‑suspenders to catch any stray checkpoint files that may have been copied out of the folder.

If you use pre‑commit, you can also enforce cleanup:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: clean-ipynb-checkpoints
        name: Remove Jupyter checkpoints
        language: system
        pass_filenames: false
        entry: bash -c 'find . -name "*-checkpoint.ipynb" -delete && find . -type d -name ".ipynb_checkpoints" -empty -delete'

Clean up checkpoints safely

Linux/macOS (bash)

Delete only checkpoint files:

find . -name "*-checkpoint.ipynb" -delete

Remove empty .ipynb_checkpoints folders afterward:

find . -type d -name ".ipynb_checkpoints" -empty -delete

Windows (PowerShell)

Get-ChildItem -Recurse -Filter *-checkpoint.ipynb | Remove-Item
Get-ChildItem -Recurse -Directory -Filter .ipynb_checkpoints | Remove-Item -Recurse -Force

Tip: Prefer deleting files first, then removing now‑empty directories. This minimizes the chance of deleting unrelated content if paths were nested in unexpected ways.

Reverting to a checkpoint

If you haven’t deleted them yet:

• JupyterLab: File → Revert Notebook to Checkpoint → pick the desired snapshot.
• Classic Notebook: File → Revert to Checkpoint → choose from the list.

If the option is disabled or empty, there are no checkpoints yet for that notebook.

Autosave and configuration tips

• Autosave interval is configurable in JupyterLab (Settings → Advanced Settings Editor → Notebook → autosaveInterval in milliseconds). A shorter interval reduces data‑loss risk but may write more frequently.
• If you turn off autosave, manual saves will still create/update checkpoints in many front‑ends. Expect .ipynb_checkpoints to show up again when you save.

There isn’t a universally supported, single “disable checkpoints forever” switch. The safest pattern is to ignore and clean them rather than trying to disable the mechanism.

CI/CD & packaging

• GitHub Actions / CI: Add the cleanup commands as a step before caching artifacts or publishing wheels/docs.
• Docker images: Use .dockerignore to prevent copying checkpoints into build context; if already copied, delete them in a build stage.
• Archives/exports: Run cleanup before zipping or releasing datasets/notebooks to avoid leaking large outputs or sensitive cells captured in a checkpoint.

Security & privacy notes

• Checkpoints may contain cell outputs (e.g., partial results, printed secrets) that existed when the snapshot was taken.
• If you’re publishing a public repo, treat checkpoints as sensitive: ensure they are ignored, or explicitly cleaned.

FAQ

Q: My repo keeps showing new *-checkpoint.ipynb files even with .gitignore. Why? A: They were likely committed before the ignore rule existed. Remove them from the index:

git rm -r --cached .
git add .
git commit -m "Stop tracking Jupyter checkpoints"

Q: Can I use checkpoints as ‘real’ versioning? A: They’re best for local, short‑term rollback, not for collaboration history. Use Git (optionally with tools like nbdime) for meaningful diffs and merges.

Q: Do other notebook tools create the same folder? A: Not all. Behavior depends on the front‑end. Jupyter’s classic UI and JupyterLab commonly do; others may rely on different backup systems.

Recommended defaults

• Keep checkpoints enabled (they’re handy).
• Ignore them in VCS and build contexts.
• Clean them in CI and before publishing.

That balance gives you fast local safety with clean, lightweight repositories.