Commenting & Discussion on Jupyter Notebook Cells

Quick answer: GitHub pull requests don’t support threaded comments on individual Jupyter notebook cells. ReviewNB adds cell-level commenting on GitHub PRs (rich diff + threaded discussion that persists across commits), and its JDoc feature lets you comment on standalone notebooks without a PR. Install it on a repo in two clicks via the GitHub Marketplace.

Collaboration is essential to our work in Jupyter notebooks and being able to comment on notebook cells is key to facilitating discussions with team members and other stakeholders.

During technical code reviews, for example, you might like your colleagues to comment on notebook cells to provide feedback, find bugs, and suggest improvements. Doing this kind of review on pull requests is ideal, as it’s easy to see what’s changed in notebook diffs.

But the review process doesn’t always call for you to create a pull request. Notebook diffs may not be valuable at every stage of the review process and not all stakeholders are proficient in Git or GitHub. Business and other stakeholders, for example, may prefer to share and review the final version of your notebook to ask questions and make decisions. When reviewing standalone notebook files, being able to comment on cells in the same way as we leave comments in Google Docs is more helpful.

ReviewNB is your solution for both types of commenting needs. For notebook code reviews, ReviewNB renders rich diffs of your GitHub commits and pull requests with the ability to comment on the cell or line level. For reviewing standalone notebook files, the ReviewNB JDoc feature enables a user to open any notebook in their GitHub repo and start commenting on any cell. It’s like Google Docs for Jupyter!

Let’s take a look at these two review workflows in ReviewNB.

Commenting on Jupyter Notebook pull requests

With ReviewNB, you can see rendered rich diffs of code changes on your pull requests and start discussions on your commits and PRs.

To comment on pull requests in ReviewNB, find the appropriate pull request on GitHub. Under the Conversation tab, find the ReviewNB bot’s message and click on the purple ReviewNB button.

You’ll see the rich diff view of the changes on the pull request. Click the + button at the single-line or cell level to start a discussion.

You can make comments on individual lines and cells, on the PR, or on the notebook. Segmenting your review in this way allows your team to focus on either cell-specific discussion or high-level PR concerns.

Commenting on notebooks without making a pull request

JDoc provides a simple and efficient way for teams to review Jupyter notebooks without having to create a pull request. This approach can be especially useful for:

• Ad-hoc analysis.
• A user that is not proficient with Git or GitHub.
• Reviewing newly added notebooks.
• Reviewing the final notebook version when incremental updates are not a concern.

To comment on your notebook using JDoc, open a repository in ReviewNB and navigate to the NOTEBOOKS tab.

Open the notebook you want to comment on and click the + button on either the single-line or cell level.

Once you’ve made a comment, any team member that is watching the repository or has participated in the conversation previously will get an email notifying them of the new comment. Users can unsubscribe from email notifications in the ReviewNB UI.

Users can reply, resolve, and start a new conversation or just skim through the comments.

Use the CHANGES tab to view the version history of this notebook.

JDoc tips:

• Make sure to either resolve or delete discussions that are no longer important to keep the notebook clear and relevant.

• Unlike discussions on pull requests, comments made on the notebook with JDoc will not reflect on GitHub. This is because GitHub does not support review outside of pull requests and commits

• Currently, if you change the name of a notebook, ReviewNB will treat it as a new notebook and previous JDoc discussions will no longer be visible. In future, we’ll provide a UI to specify renames and port over the comments.

Other methods for reviewing notebooks

Here are a few other options for leaving comments in notebooks, and where each one falls short.

• GitHub’s native PR view. GitHub now renders a rich, cell-by-cell notebook diff in pull requests (as an opt-in feature preview), but does not allow review comments on the rich view — comments only work on the raw JSON diff, which is unreadable for notebooks. This is especially painful when larger notebooks fail to render on GitHub at all.

• Local Git tools like the JupyterLab Git extension and nbdime show rich diffs on your machine but don’t add commenting to GitHub pull requests — they handle the write/diff/merge side of the workflow, not the review side.

• A quick and easy way to give and receive feedback on notebooks is to share screenshots on Slack, but this is not an efficient way to manage the review as information can easily get lost or overlooked.

FAQ

Can you comment on Jupyter notebook cells in a GitHub PR?

Not with GitHub’s built-in review. GitHub renders a rich notebook diff on pull requests (opt-in preview), but doesn’t let you leave review comments on it — comments only attach to the raw JSON diff. ReviewNB adds threaded cell-level comments on top of the rich diff, on the same GitHub PR.

How do I review a notebook without making a pull request?

Use ReviewNB’s JDoc feature: open the notebook in a connected repository and click the + on any cell to start a thread. Useful for ad-hoc analysis, sharing finished notebooks with non-technical stakeholders, or reviewing standalone notebook files.

Does GitHub support comments on notebook rich diffs?

No. The rich diff view is read-only; to leave a review comment you have to switch back to the raw JSON diff, which is unreadable for notebooks. For threaded discussion on a rich notebook diff, you need a notebook-aware tool such as ReviewNB.

Can you comment on notebook cells in JupyterLab or VS Code?

No, these editors show rich diffs but don’t have a per-cell discussion thread that persists across commits. They handle authoring and local diff/merge; cell-level review comments on a pull request need a GitHub-integrated tool like ReviewNB.

Conclusion

Performing reviews on Jupyter notebooks is an essential workflow for data science and ML teams. While pull request reviews offer valuable benefits like commenting with visual diffs, this workflow does not suit every circumstance.

Your best solution for leaving comments on notebooks is ReviewNB. It adds threaded cell-level comments on GitHub pull requests, and its JDoc feature lets you review standalone notebooks without a PR. Install it on your GitHub repo in two clicks via the GitHub Marketplace. Teams at Apple, Airbnb, Spotify, and NASA JPL use ReviewNB, and the service is free for open source and education.