Traitlets: Python Configuration System

5.14.3 verified Tue May 12 auth: no python install: verified quickstart: verified

Traitlets is a Python library that provides a framework for defining attributes with type checking, dynamic default values, and change callbacks. It is currently at version 5.14.3, released on April 19, 2024, and follows a regular release cadence with periodic updates and maintenance improvements.

pip install traitlets

Common errors

error TraitError: The 'my_trait' trait of a MyClass instance must be an int, but a value of 'hello' <class 'str'> was specified. ↓

cause This error occurs when you attempt to assign a value of an incorrect type to a traitlet-defined attribute.

fix

Assign a value that matches the traitlet's specified type (e.g., an int for an Int trait, a str for a Unicode trait).

error traitlets.config.loader.ConfigError: No such config option: 'MyClass.some_nonexistent_trait' ↓

cause This error indicates that a configuration file (e.g., for a Jupyter application) attempts to set a traitlet that either does not exist, is misspelled, or is not applicable to the specified class.

fix

Review your configuration file and correct the traitlet option name, ensuring it matches an existing trait on the target class.

error TypeError: _default_my_trait() missing 1 required positional argument: 'owner' ↓

cause This error arises when you define a method to provide a dynamic default value for a traitlet (e.g., `_default_my_trait`) but omit the `owner` argument from its signature.

fix

Add the owner argument to the method signature: def _default_my_trait(self, owner): return some_value.

Warnings

breaking Traitlets 5.0 removed support for Python 2 and versions 3.0-3.6, now requiring Python 3.7 or higher. ↓

fix Upgrade your Python environment to version 3.7 or higher.

deprecated The 'six' library is no longer a dependency as of Traitlets 5.0.0. ↓

fix Ensure your code does not rely on 'six' for compatibility between Python 2 and 3.

gotcha Using 'default' as a method name without the '@default' decorator will not set the default value for the trait. ↓

fix Decorate the method with '@default('trait_name')' to set the default value.

gotcha The pip tool issued a warning about being run as the 'root' user, which can cause broken permissions and conflicts with the system package manager. ↓

fix Avoid running pip directly as the 'root' user. It is recommended to use a virtual environment (`python -m venv`) or install packages for the user (`pip install --user`). The `--root-user-action` option can suppress this warning if intended.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.5M

3.10 slim (glibc) - - 0.03s 19M

3.11 alpine (musl) - - 0.09s 20.4M

3.11 slim (glibc) - - 0.07s 21M

3.12 alpine (musl) - - 0.07s 12.3M

3.12 slim (glibc) - - 0.07s 13M

3.13 alpine (musl) - - 0.07s 11.9M

3.13 slim (glibc) - - 0.07s 12M

3.9 alpine (musl) - - 0.04s 18.0M

3.9 slim (glibc) - - 0.04s 18M

Imports

HasTraits
```
from traitlets import HasTraits
```
Correct import path for defining classes with trait attributes.
Unicode
```
from traitlets import Unicode
```
Correct import path for defining Unicode trait attributes.
Int
```
from traitlets import Int
```
Correct import path for defining Integer trait attributes.
default
```
from traitlets import default
```
Correct import path for defining default values for traits.

Quickstart verified last tested: 2026-04-23

A simple example demonstrating the use of Traitlets to define a class with a 'username' attribute that defaults to the current system user.

import getpass
from traitlets import HasTraits, Unicode, default

class Identity(HasTraits):
    username = Unicode()

    @default('username')
    def _default_username(self):
        return getpass.getuser()

identity = Identity()
print(identity.username)