{"id":457,"library":"traitlets","title":"Traitlets: Python Configuration System","description":"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.","status":"active","version":"5.14.3","language":"python","source_language":"en","source_url":"https://github.com/ipython/traitlets","tags":["configuration","type checking","Python attributes","traitlets","IPython","Jupyter"],"install":[{"cmd":"pip install traitlets","lang":"bash","label":"Install Traitlets"}],"dependencies":[{"reason":"Provides utility functions for IPython components.","package":"ipython_genutils"},{"reason":"Ensures compatibility between Python 2 and 3.","package":"six"},{"reason":"Simplifies the creation of decorators.","package":"decorator"}],"imports":[{"note":"Correct import path for defining classes with trait attributes.","symbol":"HasTraits","correct":"from traitlets import HasTraits"},{"note":"Correct import path for defining Unicode trait attributes.","symbol":"Unicode","correct":"from traitlets import Unicode"},{"note":"Correct import path for defining Integer trait attributes.","symbol":"Int","correct":"from traitlets import Int"},{"note":"Correct import path for defining default values for traits.","symbol":"default","correct":"from traitlets import default"}],"quickstart":{"code":"import getpass\nfrom traitlets import HasTraits, Unicode, default\n\nclass Identity(HasTraits):\n    username = Unicode()\n\n    @default('username')\n    def _default_username(self):\n        return getpass.getuser()\n\nidentity = Identity()\nprint(identity.username)","lang":"python","description":"A simple example demonstrating the use of Traitlets to define a class with a 'username' attribute that defaults to the current system user."},"warnings":[{"fix":"Upgrade your Python environment to version 3.7 or higher.","message":"Traitlets 5.0 removed support for Python 2 and versions 3.0-3.6, now requiring Python 3.7 or higher.","severity":"breaking","affected_versions":"5.0.0"},{"fix":"Ensure your code does not rely on 'six' for compatibility between Python 2 and 3.","message":"The 'six' library is no longer a dependency as of Traitlets 5.0.0.","severity":"deprecated","affected_versions":"5.0.0"},{"fix":"Decorate the method with '@default('trait_name')' to set the default value.","message":"Using 'default' as a method name without the '@default' decorator will not set the default value for the trait.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T13:56:41.596Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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).","cause":"This error occurs when you attempt to assign a value of an incorrect type to a traitlet-defined attribute.","error":"TraitError: The 'my_trait' trait of a MyClass instance must be an int, but a value of 'hello' <class 'str'> was specified."},{"fix":"Review your configuration file and correct the traitlet option name, ensuring it matches an existing trait on the target class.","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.","error":"traitlets.config.loader.ConfigError: No such config option: 'MyClass.some_nonexistent_trait'"},{"fix":"Add the `owner` argument to the method signature: `def _default_my_trait(self, owner): return some_value`.","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.","error":"TypeError: _default_my_trait() missing 1 required positional argument: 'owner'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.4,"disk_size":"18.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":2.4,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.09,"mem_mb":2.8,"disk_size":"20.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.8,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.8,"disk_size":"12.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.8,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.7,"disk_size":"11.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.5,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.4,"disk_size":"18.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":2.4,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}