Traitlets config API reference#

class traitlets.config.Configurable(**kwargs: Any)#
classmethod class_config_rst_doc()#

Generate rST documentation for this class’ config options.

Excludes traits defined on parent classes.

classmethod class_config_section(classes=None)#

Get the config section for this class.


classes (list, optional) – The list of other classes in the config file. Used to reduce redundant information.

classmethod class_get_help(inst=None)#

Get the help string for this class in ReST format.

If inst is given, its current trait values will be used in place of class defaults.

classmethod class_get_trait_help(trait, inst=None, helptext=None)#

Get the helptext string for a single trait.

  • inst – If given, its current trait values will be used in place of the class default.

  • helptext – If not given, uses the help attribute of the current trait.

classmethod class_print_help(inst=None)#

Get the help string for a single trait and print it.

classmethod section_names()#

return section names as a list


Update config and load the new values

class traitlets.config.SingletonConfigurable(**kwargs: Any)#

A configurable that only allows one instance.

This class is for classes that should only have one instance of itself or any subclass. To create and retrieve such a class use the SingletonConfigurable.instance() method.

classmethod clear_instance()#

unset _instance for this class and singleton parents.

classmethod initialized()#

Has an instance been created?

classmethod instance(*args, **kwargs)#

Returns a global instance of this class.

This method create a new instance if none have previously been created and returns a previously created instance is one already exists.

The arguments and keyword arguments passed to this method are passed on to the __init__() method of the class upon instantiation.


Create a singleton class using instance, and retrieve it:

>>> from traitlets.config.configurable import SingletonConfigurable
>>> class Foo(SingletonConfigurable): pass
>>> foo = Foo.instance()
>>> foo == Foo.instance()

Create a subclass that is retrived using the base class instance:

>>> class Bar(SingletonConfigurable): pass
>>> class Bam(Bar): pass
>>> bam = Bam.instance()
>>> bam == Bar.instance()
class traitlets.config.LoggingConfigurable(**kwargs: Any)#

A parent class for Configurables that log.

Subclasses have a log trait, and the default behavior is to get the logger from the currently running Application.


Logger or LoggerAdapter instance

class traitlets.config.JSONFileConfigLoader(filename, path=None, **kw)#

A JSON file loader for config

Can also act as a context manager that rewrite the configuration file to disk on exit.


with JSONFileConfigLoader('myapp.json','/home/jupyter/configurations/') as c:
    c.MyNewConfigurable.new_value = 'Updated'

Load the config from a file and return it as a Config object.

class traitlets.config.Application(**kwargs: Any)#

A singleton application with full configuration support.


The subset of our configuration that came from the command-line

We re-load this configuration after loading config files, to ensure that it maintains highest priority.


Generate rST format documentation for the config options this application

Returns a multiline string.


Yield the lines for alias part of the help.


Yield lines with the application description.


Yield lines with the usage and examples.

This usage string goes at the end of the command line help string and should contain examples of the application’s usage.


Yield the lines for the flag part of the help.


Yield the help-lines for each Configurable class in self.classes.

If classes=False (the default), only flags and aliases are printed.


Yield the very bottom lines of the help message.

If classes=False (the default), print –help-all msg.


Yield the lines for the options part of the help.


Yield the lines for the subcommand part of the help.


Flatten flags and aliases for loaders, so cl-args override as expected.

This prevents issues such as an alias pointing to InteractiveShell, but a config file setting the same trait in TerminalInteraciveShell getting inappropriate priority over the command-line arg. Also, loaders expect (key: longname) and not key: (longname, help) items.

Only aliases with exactly one descendent in the class list will be promoted.


generate default config file from Configurables


Return the base logging configuration.

The default is to log to stderr using a StreamHandler, if no default handler already exists.

The log handler level starts at logging.WARN, but this can be adjusted by setting the log_level attribute.

The logging_config trait is merged into this allowing for finer control of logging.


Do the basic steps to configure me.

Override in subclasses.

initialize_subcommand(subc, argv=None)#

Initialize a subcommand with argv.


alias of JSONFileConfigLoader

classmethod launch_instance(argv=None, **kwargs)#

Launch a global instance of this Application

If a global instance already exists, this reinitializes and starts it

load_config_file(filename, path=None)#

Load config files by filename and path.

property loaded_config_files#

Currently loaded configuration files

log_datefmt: str | Unicode#

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

log_format: str | Unicode#

The Logging format template

log_level: str | int | Enum#

Set the log level by value or name.


Configure additional log handlers.

The default stderr logs handler is configured by the log_level, log_datefmt and log_format settings.

This configuration can be used to configure additional handlers (e.g. to output the log to a file) or for finer control over the default handlers.

If provided this should be a logging configuration dictionary, for more information see:

This dictionary is merged with the base logging configuration which defines the following:

  • A logging formatter intended for interactive use called console.

  • A logging handler that writes to stderr called console which uses the formatter console.

  • A logger with the name of this application set to DEBUG level.

This example adds a new handler that writes to a file:

c.Application.logging_config = {
    'handlers': {
        'file': {
            'class': 'logging.FileHandler',
            'level': 'DEBUG',
            'filename': '<path/to/file>',
    'loggers': {
        '<application-name>': {
            'level': 'DEBUG',
            # NOTE: if you don't list the default "console"
            # handler here then it will be disabled
            'handlers': ['console', 'file'],

Parse the command line arguments.


Print the alias parts of the help.


Print the application description.


Print usage and examples (see emit_examples()).


Print the flag part of the help.


Print the help for each Configurable class in self.classes.

If classes=False (the default), only flags and aliases are printed.


Print the options part of the help.


Print the subcommand part of the help.


Print the version string.


alias of PyFileConfigLoader

show_config: bool | Bool#

Instead of starting the Application, dump configuration to stdout

show_config_json: bool | Bool#

Instead of starting the Application, dump configuration to stdout (as JSON)


Start the app mainloop.

Override in subclasses.


start function used when show_config is True

class traitlets.config.Config(*args, **kwds)#

An attribute-based dict that can do smart merges.

Accessing a field on a config object for the first time populates the key with either a nested Config object for keys starting with capitals or LazyConfigValue for lowercase keys, allowing quick assignments such as:

c = Config()
c.Class.int_trait = 5
collisions(other: Config) Dict[str, Any]#

Check for collisions between two config objects.

Returns a dict of the form {“Class”: {“trait”: “collision message”}}`, indicating which values have been ignored.

An empty dict indicates no collisions.

copy() a shallow copy of D#

True if the dictionary has the specified key, else False.


merge another config object into this one

class traitlets.config.loader.LazyConfigValue(**kwargs: Any)#

Proxy object for exposing methods on configurable containers

These methods allow appending/extending/updating to add to non-empty defaults instead of clobbering them.


  • append, extend, insert on lists

  • update on dicts

  • update, add on sets


Add an item to a set


Append an item to a List


Extend a list


construct the value from the initial one

after applying any insert / extend / update changes


Merge with another earlier LazyConfigValue or an earlier container. This is useful when having global system-wide configuration files.

Self is expected to have higher precedence.


other (LazyConfigValue or container) –


if other is also lazy, a reified container otherwise.

Return type:



like list.extend, but for the front


return JSONable dict form of my data

Currently update as dict or set, extend, prepend as lists, and inserts as list of tuples.


Update either a set or dict

class traitlets.config.loader.KVArgParseConfigLoader(argv: List[str] | None = None, aliases: Dict[str | Tuple[str, ...], str] | None = None, flags: Dict[str | Tuple[str, ...], str] | None = None, log: Any | None = None, classes: List[Type[Any]] | None = None, subcommands: Dict[str, Any] | None = None, *parser_args: Any, **parser_kw: Any)#

A config loader that loads aliases and flags with argparse,

as well as arbitrary –Class.trait value

__init__(argv: List[str] | None = None, aliases: Dict[str | Tuple[str, ...], str] | None = None, flags: Dict[str | Tuple[str, ...], str] | None = None, log: Any | None = None, classes: List[Type[Any]] | None = None, subcommands: Dict[str, Any] | None = None, *parser_args: Any, **parser_kw: Any) None#

Create a config loader for use with argparse.

  • classes (optional, list) – The classes to scan for container config-traits and decide for their “multiplicity” when adding them as argparse arguments.

  • argv (optional, list) – If given, used to read command-line arguments from, otherwise sys.argv[1:] is used.

  • *parser_args (tuple) – A tuple of positional arguments that will be passed to the constructor of argparse.ArgumentParser.

  • **parser_kw (dict) – A tuple of keyword arguments that will be passed to the constructor of argparse.ArgumentParser.

  • aliases (dict of str to str) – Dict of aliases to full traitlets names for CLI parsing

  • flags (dict of str to str) – Dict of flags to full traitlets names for CLI parsing

  • log – Passed to ConfigLoader


config – The resulting Config object.

Return type:


load_config(argv=None, aliases=None, flags=<Sentinel deprecated>, classes=None)#

Parse command line arguments and return as a Config object.

  • argv (optional, list) – If given, a list with the structure of sys.argv[1:] to parse arguments from. If not given, the instance’s self.argv attribute (given at construction time) is used.

  • flags – Deprecated in traitlets 5.0, instanciate the config loader with the flags.