Configuration options

See also

The nbgrader_config.py file

Details on how to setup the nbgrader_config.py file.

These options can be set in nbgrader_config.py, or at the command line when you start it.

Application.log_datefmtUnicode

Default: '%Y-%m-%d %H:%M:%S'

The date format used by logging formatters for %(asctime)s

Application.log_formatUnicode

Default: '[%(name)s]%(highlevel)s %(message)s'

The Logging format template

Application.log_level0|10|20|30|40|50|’DEBUG’|’INFO’|’WARN’|’ERROR’|’CRITICAL’

Default: 30

Set the log level by value or name.

JupyterApp.answer_yesBool

Default: False

Answer yes to any prompts.

JupyterApp.config_fileUnicode

Default: ''

Full path of a config file.

JupyterApp.config_file_nameUnicode

Default: ''

Specify a config file to load.

JupyterApp.generate_configBool

Default: False

Generate default config file.

NbGrader.logfileUnicode

Default: ''

Name of the logfile to log to. By default, log output is not written to any file.

CourseDirectory.assignment_idUnicode

Default: ''

The assignment name. This MUST be specified, either by setting the config option, passing an argument on the command line, or using the –assignment option on the command line.

CourseDirectory.autograded_directoryUnicode

Default: 'autograded'

The name of the directory that contains assignment submissions after they have been autograded. This corresponds to the nbgrader_step variable in the directory_structure config option.

CourseDirectory.course_idUnicode

Default: ''

A key that is unique per instructor and course. This can be specified, either by setting the config option, or using the –course option on the command line.

CourseDirectory.db_assignmentsList

Default: []

A list of assignments that will be created in the database. Each item in the list should be a dictionary with the following keys:

  • name

  • duedate (optional)

The values will be stored in the database. Please see the API documentation on the Assignment database model for details on these fields.

CourseDirectory.db_studentsList

Default: []

A list of student that will be created in the database. Each item in the list should be a dictionary with the following keys:

  • id

  • first_name (optional)

  • last_name (optional)

  • email (optional)

The values will be stored in the database. Please see the API documentation on the Student database model for details on these fields.

CourseDirectory.db_urlUnicode

Default: ''

URL to the database. Defaults to sqlite:///<root>/gradebook.db, where <root> is another configurable variable.

CourseDirectory.directory_structureUnicode

Default: '{nbgrader_step}/{student_id}/{assignment_id}'

Format string for the directory structure that nbgrader works over during the grading process. This MUST contain named keys for ‘nbgrader_step’, ‘student_id’, and ‘assignment_id’. It SHOULD NOT contain a key for ‘notebook_id’, as this will be automatically joined with the rest of the path.

CourseDirectory.feedback_directoryUnicode

Default: 'feedback'

The name of the directory that contains assignment feedback after grading has been completed. This corresponds to the nbgrader_step variable in the directory_structure config option.

CourseDirectory.groupsharedBool

Default: False

Make all instructor files group writeable (g+ws, default g+r only) and exchange directories group readable/writeable (g+rws, default g=nothing only ) by default. This should only be used if you carefully set the primary groups of your notebook servers and fully understand the unix permission model. This changes the default permissions from 444 (unwriteable) to 664 (writeable), so that other instructors are able to delete/overwrite files.

CourseDirectory.ignoreList

Default: ['.ipynb_checkpoints', '*.pyc', '__pycache__', 'feedback']

List of file names or file globs. Upon copying directories recursively, matching files and directories will be ignored with a debug message.

CourseDirectory.includeList

Default: ['*']

List of file names or file globs. Upon copying directories recursively, non matching files will be ignored with a debug message.

CourseDirectory.max_file_sizeInt

Default: 100000

Maximum size of files (in kilobytes; default: 100Mb). Upon copying directories recursively, larger files will be ignored with a warning.

CourseDirectory.notebook_idUnicode

Default: '*'

File glob to match notebook names, excluding the ‘.ipynb’ extension. This can be changed to filter by notebook.

CourseDirectory.release_directoryUnicode

Default: 'release'

The name of the directory that contains the version of the assignment that will be released to students. This corresponds to the nbgrader_step variable in the directory_structure config option.

CourseDirectory.rootUnicode

Default: ''

The root directory for the course files (that includes the source, release, submitted, autograded, etc. directories). Defaults to the current working directory.

CourseDirectory.source_directoryUnicode

Default: 'source'

The name of the directory that contains the master/instructor version of assignments. This corresponds to the nbgrader_step variable in the directory_structure config option.

CourseDirectory.student_idUnicode

Default: '*'

File glob to match student IDs. This can be changed to filter by student. Note: this is always changed to ‘.’ when running nbgrader assign, as the assign step doesn’t have any student ID associated with it. With nbgrader submit, this instead forces the use of an alternative student ID for the submission. See nbgrader submit –help.

If the ID is purely numeric and you are passing it as a flag on the command line, you will need to escape the quotes in order to have it detected as a string, for example –student=”“12345”“. See:

for more details.

CourseDirectory.student_id_excludeUnicode

Default: ''

Comma-separated list of student IDs to exclude. Counterpart of student_id.

This is useful when running commands on all students, but certain students cause errors or otherwise must be left out. Works at least for autograde, generate_feedback, and release_feedback.

CourseDirectory.submitted_directoryUnicode

Default: 'submitted'

The name of the directory that contains assignments that have been submitted by students for grading. This corresponds to the nbgrader_step variable in the directory_structure config option.

Authenticator.plugin_classType

Default: 'nbgrader.auth.base.NoAuthPlugin'

A plugin for different authentication methods.

ZipCollectApp.archive_directoryUnicode

Default: 'archive'

The name of the directory that contains assignment submission files and/or archives (zip) files manually downloaded from a LMS. This corresponds to the collect_step variable in the collect_structure config option.

ZipCollectApp.collect_directory_structureUnicode

Default: '{downloaded}/{assignment_id}/{collect_step}'

Format string for the directory structure that nbgrader works over during the zip collect process. This MUST contain named keys for ‘downloaded’, ‘assignment_id’, and ‘collect_step’.

ZipCollectApp.collector_pluginType

Default: 'nbgrader.plugins.zipcollect.FileNameCollectorPlugin'

The plugin class for processing the submitted file names after they have been extracted into the extracted_directory.

ZipCollectApp.downloaded_directoryUnicode

Default: 'downloaded'

The main directory that corresponds to the downloaded variable in the collect_structure config option.

ZipCollectApp.extracted_directoryUnicode

Default: 'extracted'

The name of the directory that contains assignment submission files extracted or copied from the archive_directory. This corresponds to the collect_step variable in the collect_structure config option.

ZipCollectApp.extractor_pluginType

Default: 'nbgrader.plugins.zipcollect.ExtractorPlugin'

The plugin class for extracting the archive files in the archive_directory.

ZipCollectApp.forceBool

Default: False

Force overwrite of existing files.

ZipCollectApp.strictBool

Default: False

Skip submitted notebooks with invalid names.

QuickStartApp.forceBool

Default: False

Whether to overwrite existing files

ExportApp.plugin_classType

Default: 'nbgrader.plugins.export.CsvExportPlugin'

The plugin class for exporting the grades.

UpdateApp.validateBool

Default: True

whether to validate metadata after updating it

GenerateConfigApp.filenameUnicode

Default: 'nbgrader_config.py'

The name of the configuration file to generate.

ExportPlugin.assignmentList

Default: []

list of assignments to export

ExportPlugin.studentList

Default: []

list of students to export

ExportPlugin.toUnicode

Default: ''

destination to export to

ExtractorPlugin.forceBool

Default: False

Force overwrite of existing files.

ExtractorPlugin.zip_extList

Default: ['.zip', '.gz']

List of valid archive (zip) filename extensions to extract. Any archive (zip) files with an extension not in this list are copied to the extracted_directory.

FileNameCollectorPlugin.named_regexpUnicode

Default: ''

This regular expression is applied to each submission filename and MUST be supplied by the instructor. This regular expression MUST provide the (?P<student_id>…) and (?P<file_id>…) named group expressions. Optionally this regular expression can also provide the (?P<first_name>…), (?P<last_name>…), (?P<email>…), and (?P<timestamp>…) named group expressions. For example if the filename is:

ps1_bitdiddle_attempt_2016-01-30-15-00-00_problem1.ipynb

then this named_regexp could be:

“.*_(?P<student_id>w+)_attempt_(?P<timestamp>[0-9-]+)_(?P<file_id>w+)”

For named group regular expression examples see https://docs.python.org/3/howto/regex.html

FileNameCollectorPlugin.valid_extList

Default: ['.ipynb']

List of valid submission filename extensions to collect. Any submitted file with an extension not in this list is skipped.

LateSubmissionPlugin.penalty_method‘none’|’zero’

Default: 'none'

The method for assigning late submission penalties:

‘none’: do nothing (no penalty assigned) ‘zero’: assign an overall score of zero (penalty = score)

NbConvertBase.default_languageUnicode

Default: 'ipython'

Deprecated default highlight language as of 5.0, please use language_info metadata instead

NbConvertBase.display_data_priorityList

Default: ['text/html', 'application/pdf', 'text/latex', 'image/svg+xml...

An ordered list of preferred output type, the first encountered will usually be used when converting discarding the others.

Preprocessor.enabledBool

Default: False

No description

NbGraderPreprocessor.enabledBool

Default: True

Whether to use this preprocessor when running nbgrader

AssignLatePenalties.plugin_classType

Default: 'nbgrader.plugins.latesubmission.LateSubmissionPlugin'

The plugin class for assigning the late penalty for each notebook.

IncludeHeaderFooter.footerUnicode

Default: ''

Path to footer notebook, relative to the root of the course directory

IncludeHeaderFooter.headerUnicode

Default: ''

Path to header notebook, relative to the root of the course directory

LockCells.lock_all_cellsBool

Default: False

Whether all assignment cells are locked (non-deletable and non-editable)

LockCells.lock_grade_cellsBool

Default: True

Whether grade cells are locked (non-deletable)

LockCells.lock_readonly_cellsBool

Default: True

Whether readonly cells are locked (non-deletable and non-editable)

LockCells.lock_solution_cellsBool

Default: True

Whether solution cells are locked (non-deletable and non-editable)

ClearSolutions.begin_solution_delimeterUnicode

Default: 'BEGIN SOLUTION'

The delimiter marking the beginning of a solution

ClearSolutions.code_stubDict

Default: {'python': '# YOUR CODE HERE\\nraise NotImplementedError()', '...

The code snippet that will replace code solutions

ClearSolutions.end_solution_delimeterUnicode

Default: 'END SOLUTION'

The delimiter marking the end of a solution

ClearSolutions.enforce_metadataBool

Default: True

Whether or not to complain if cells containing solutions regions are not marked as solution cells. WARNING: this will potentially cause things to break if you are using the full nbgrader pipeline. ONLY disable this option if you are only ever planning to use nbgrader assign.

ClearSolutions.text_stubUnicode

Default: 'YOUR ANSWER HERE'

The text snippet that will replace written solutions

ExecutePreprocessor.allow_errorsBool

Default: False

If False (default), when a cell raises an error the execution is stopped and a CellExecutionError is raised. If True, execution errors are ignored and the execution is continued until the end of the notebook. Output from exceptions is included in the cell output in both cases.

ExecutePreprocessor.force_raise_errorsBool

Default: False

If False (default), errors from executing the notebook can be allowed with a raises-exception tag on a single cell, or the allow_errors configurable option for all cells. An allowed error will be recorded in notebook output, and execution will continue. If an error occurs when it is not explicitly allowed, a CellExecutionError will be raised. If True, CellExecutionError will be raised for any error that occurs while executing the notebook. This overrides both the allow_errors option and the raises-exception cell tag.

ExecutePreprocessor.interrupt_on_timeoutBool

Default: False

If execution of a cell times out, interrupt the kernel and continue executing other cells rather than throwing an error and stopping.

ExecutePreprocessor.iopub_timeoutInt

Default: 4

The time to wait (in seconds) for IOPub output. This generally doesn’t need to be set, but on some slow networks (such as CI systems) the default timeout might not be long enough to get all messages.

ExecutePreprocessor.ipython_hist_fileUnicode

Default: ':memory:'

Path to file to use for SQLite history database for an IPython kernel.

The specific value :memory: (including the colon at both end but not the back ticks), avoids creating a history file. Otherwise, IPython will create a history file for each kernel.

When running kernels simultaneously (e.g. via multiprocessing) saving history a single SQLite file can result in database errors, so using :memory: is recommended in non-interactive contexts.

ExecutePreprocessor.kernel_manager_classType

Default: 'builtins.object'

The kernel manager class to use.

ExecutePreprocessor.kernel_nameUnicode

Default: ''

Name of kernel to use to execute the cells. If not set, use the kernel_spec embedded in the notebook.

ExecutePreprocessor.raise_on_iopub_timeoutBool

Default: False

If False (default), then the kernel will continue waiting for iopub messages until it receives a kernel idle message, or until a timeout occurs, at which point the currently executing cell will be skipped. If True, then an error will be raised after the first timeout. This option generally does not need to be used, but may be useful in contexts where there is the possibility of executing notebooks with memory-consuming infinite loops.

ExecutePreprocessor.shutdown_kernel‘graceful’|’immediate’

Default: 'graceful'

If graceful (default), then the kernel is given time to clean up after executing all cells, e.g., to execute its atexit hooks. If immediate, then the kernel is signaled to immediately terminate.

ExecutePreprocessor.startup_timeoutInt

Default: 60

The time to wait (in seconds) for the kernel to start. If kernel startup takes longer, a RuntimeError is raised.

ExecutePreprocessor.store_widget_stateBool

Default: True

If True (default), then the state of the Jupyter widgets created at the kernel will be stored in the metadata of the notebook.

ExecutePreprocessor.timeoutInt

Default: 30

The time to wait (in seconds) for output from executions. If a cell execution takes longer, an exception (TimeoutError on python 3+, RuntimeError on python 2) is raised.

None or -1 will disable the timeout. If timeout_func is set, it overrides timeout.

ExecutePreprocessor.timeout_funcAny

Default: None

A callable which, when given the cell source as input, returns the time to wait (in seconds) for output from cell executions. If a cell execution takes longer, an exception (TimeoutError on python 3+, RuntimeError on python 2) is raised.

Returning None or -1 will disable the timeout for the cell. Not setting timeout_func will cause the preprocessor to default to using the timeout trait for all cells. The timeout_func trait overrides timeout if it is not None.

Execute.execute_retriesInt

Default: 0

The number of times to try re-executing the notebook before throwing an error. Generally, this shouldn’t need to be set, but might be useful for CI environments when tests are flaky.

Execute.extra_argumentsList

Default: []

A list of extra arguments to pass to the kernel. For python kernels, this defaults to --HistoryManager.hist_file=:memory:. For other kernels this is just an empty list.

GetGrades.display_data_priorityList

Default: ['text/html', 'application/pdf', 'text/latex', 'image/svg+xml...

No description

ClearOutputPreprocessor.remove_metadata_fieldsSet

Default: {'scrolled', 'collapsed'}

No description

LimitOutput.max_linesInt

Default: 1000

maximum number of lines of output (-1 means no limit)

LimitOutput.max_tracebackInt

Default: 100

maximum number of traceback lines (-1 means no limit)

ClearHiddenTests.begin_test_delimeterUnicode

Default: 'BEGIN HIDDEN TESTS'

The delimiter marking the beginning of hidden tests cases

ClearHiddenTests.end_test_delimeterUnicode

Default: 'END HIDDEN TESTS'

The delimiter marking the end of hidden tests cases

ClearHiddenTests.enforce_metadataBool

Default: True

Whether or not to complain if cells containing hidden test regions are not marked as grade cells. WARNING: this will potentially cause things to break if you are using the full nbgrader pipeline. ONLY disable this option if you are only ever planning to use nbgrader assign.

ClearMarkScheme.begin_mark_scheme_delimeterUnicode

Default: 'BEGIN MARK SCHEME'

The delimiter marking the beginning of hidden tests cases

ClearMarkScheme.end_mark_scheme_delimeterUnicode

Default: 'END MARK SCHEME'

The delimiter marking the end of hidden tests cases

ClearMarkScheme.enforce_metadataBool

Default: True

Whether or not to complain if cells containing marking scheme regions are not marked as task cells. WARNING: this will potentially cause things to break if you are using the full nbgrader pipeline. ONLY disable this option if you are only ever planning to use nbgrader assign.

Exchange.assignment_dirUnicode

Default: '.'

Local path for storing student assignments. Defaults to ‘.’ which is normally Jupyter’s notebook_dir.

Exchange.cacheUnicode

Default: ''

Local cache directory for nbgrader submit and nbgrader list. Defaults to $JUPYTER_DATA_DIR/nbgrader_cache

Exchange.path_includes_courseBool

Default: False

Whether the path for fetching/submitting assignments should be prefixed with the course name. If this is False, then the path will be something like ./ps1. If this is True, then the path will be something like ./course123/ps1.

Exchange.rootUnicode

Default: '/srv/nbgrader/exchange'

The nbgrader exchange directory writable to everyone. MUST be preexisting.

Exchange.timestamp_formatUnicode

Default: '%Y-%m-%d %H:%M:%S.%f %Z'

Format string for timestamps

Exchange.timezoneUnicode

Default: 'UTC'

Timezone for recording timestamps

ExchangeCollect.check_ownerBool

Default: True

Whether to cross-check the student_id with the UNIX-owner of the submitted directory.

ExchangeCollect.updateBool

Default: False

Update existing submissions with ones that have newer timestamps.

ExchangeFetchAssignment.replace_missing_filesBool

Default: False

Whether to replace missing files on fetch

ExchangeList.cachedBool

Default: False

List assignments in submission cache.

ExchangeList.inboundBool

Default: False

List inbound files rather than outbound.

ExchangeList.removeBool

Default: False

Remove, rather than list files.

ExchangeReleaseAssignment.forceBool

Default: False

Force overwrite existing files in the exchange.

ExchangeSubmit.add_random_stringBool

Default: True

Whether to add a random string on the end of the submission.

ExchangeSubmit.strictBool

Default: False

Whether or not to submit the assignment if there are missing notebooks from the released assignment notebooks.

BaseConverter.forceBool

Default: False

Whether to overwrite existing assignments/submissions

BaseConverter.permissionsInt

Default: 0

Permissions to set on files output by nbgrader. The default is generally read-only (444), with the exception of nbgrader generate_assignment and nbgrader generate_feedback, in which case the user also has write permission.

GenerateAssignment.create_assignmentBool

Default: True

Whether to create the assignment at runtime if it does not already exist.

GenerateAssignment.no_databaseBool

Default: False

Do not save information about the assignment into the database.

Autograde.create_studentBool

Default: True

Whether to create the student at runtime if it does not already exist.

Autograde.exclude_overwritingDict

Default: {}

A dictionary with keys corresponding to assignment names and values being a list of filenames (relative to the assignment’s source directory) that should NOT be overwritten with the source version. This is to allow students to e.g. edit a python file and submit it alongside the notebooks in their assignment.