Use nbgrader

What nbgrader is for

nbgrader is a Jupyter-based grading workflow for notebook assignments. It lets instructors create notebooks with graded cells, tests, hidden tests, feedback, and scores, then autograde submitted notebooks.

Use nbgrader when the assignment is naturally a notebook and needs structured grading. Use normal CoCalc collect/grade/return when the work is file-based, manual, or not organized around notebook cells.

Use nbgrader in a course

1. In course configuration, review the nbgrader grading project, timeouts, output limits, and parallel limit.
2. Create an instructor notebook with graded cells and tests using View -> nbgrader.
3. Choose Create Student Version... to generate the student notebook in the assignment's student/ subdirectory. Inspect that version, then assign it through the course.
4. Let students complete the notebook in their projects.
5. Collect submissions.
6. Autograde, inspect results, adjust feedback, and return grades.

Course nbgrader support is detected from notebook metadata; there is no course-wide enable switch in the configuration panel. A notebook assignment with nbgrader metadata must have a generated student version before you assign it.

Before returning notebooks, review nbgrader hidden tests in course configuration. Enabling Include the hidden tests reveals those tests in returned work.

Run a small test assignment first. nbgrader depends on notebook metadata, so editing cells carelessly or copying content through tools that drop metadata can break grading.

Resource planning

Autograding runs code. It can use significant CPU, RAM, disk, and time, especially for large classes or heavy notebooks. Tune the parallel grading limit based on the host where grading runs and the expected memory per submission.

If grading frequently hits memory limits, reduce parallelism, simplify tests, or move grading to a host with more RAM. For the memory side of these failures, see Low memory and out-of-memory crashes.

Common problems

If cells are not graded, check that the instructor notebook has the expected nbgrader metadata. If autograding hangs, inspect the exact student notebook and run the failing cells manually in a fresh kernel. If every submission fails, check the selected grading project and software environment, notebook metadata, shared test failures, and the configured grading timeouts and output limits.