Install & Compatibility
Where this runs
tested against v7.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.296s · 27.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.268s · 28MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HasTraits
✓ from traits.api import HasTraits
Str
✓ from traits.api import Str
Int
✓ from traits.api import Int
Float
✓ from traits.api import Float
Color
✓ from traitsui.api import Color
✗ from traits.api import Color
As of Traits 7.0.0, Color, RGBColor, and Font traits were moved from `traits.api` to `traitsui.api`.
Trait
✓ from traits.api import Union
✗ from traits.api import Trait
The `Trait()` function is not recommended for new code and may be deprecated; `Union` should be used instead for compound traits.
This quickstart demonstrates defining a class with various trait types (Str, Int, Float), setting default values, providing a description, and using an observer to react to trait changes. It also shows how Traits enforces type validation, raising a TraitError on invalid assignments.
from traits.api import HasTraits, Str, Float, observe
class Person(HasTraits):
name = Str('John Doe')
age = Int(30)
height = Float(175.0, desc='Height in cm')
@observe('age')
def _age_changed(self, event):
print(f"Age changed from {event.old} to {event.new}")
# Create an instance
joe = Person(name='Joe', age=25)
print(f"Initial: {joe.name}, {joe.age}, {joe.height}")
# Modify trait attributes
joe.age = 26 # This will trigger the observer
joe.height = 180.5
print(f"Updated: {joe.name}, {joe.age}, {joe.height}")
# Attempt invalid assignment (will raise TraitError)
try:
joe.age = "thirty"
except Exception as e:
print(f"Error: {e}")
Debug
Known issues
breakingPython versions earlier than 3.8 are no longer supported since Traits 7.0.0. If you are on an older Python version, you must upgrade Python or use an older Traits version (e.g., Traits 6.x for Python 3.7).fixUpgrade Python to 3.8 or newer, or pin Traits to <7.0.0 in your project dependencies.
affects: >=7.0.0
breakingThe behavior of default list or dict values for the `Any` trait type changed in Traits 7.0.0. Previously, a per-instance copy was provided; now, the default value is shared between all instances. This can lead to unexpected shared state across objects if not handled carefully.fixFor mutable default values in `Any` traits, use a dynamic default method (e.g., `_my_list_default`) or explicitly assign a new list/dict instance in each object's `__init__` if per-instance copies are desired.
affects: >=7.0.0
breakingThe `Date` trait type no longer accepts `datetime` instances by default since Traits 7.0.0. Assignments of `datetime` objects to `Date` traits will raise a `TraitError`.fixEnsure that values assigned to `Date` traits are `datetime.date` objects. Convert `datetime` instances to `datetime.date` using `my_datetime_obj.date()` before assignment.
affects: >=7.0.0
deprecatedThe `HasTraits.get()` and `HasTraits.set()` methods were removed in Traits 7.0.0. These methods were used for accessing and modifying trait values programmatically.fixDirectly access and modify trait attributes using dot notation (e.g., `obj.trait_name` for both get and set) instead of `obj.get('trait_name')` or `obj.set(trait_name=value)`. affects: >=7.0.0
deprecatedThe `Trait()` function for creating trait definitions is deprecated and not recommended for new code. It may be removed in future versions.fixUse specific trait types (e.g., `Str`, `Int`, `Float`) or `Union` for compound types instead of the generic `Trait()` function.
affects: All versions, but specifically >=7.0.0 for future removal consideration
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'traits.api'
The 'traits' package, or specifically its 'api' submodule, is not installed or accessible in the current Python environment.
TypeError: The 'my_trait' trait must be a string, but a value of type '<class 'int'>' 123 was specified.
An attempt was made to assign a value of an incorrect Python type to a trait (e.g., assigning an integer to a `Str` trait).
fixAssign a value of the correct type as defined by the trait. For `Str` traits, provide a string; for `Int` traits, an integer, etc. Example: `obj.my_trait = 'a string'`.
TraitError: The 'data' trait must be an instance of a subclass of 'numpy.ndarray', but a value of type '<class 'list'>' [...] was specified.
An attempt was made to assign a value that does not conform to a more complex `Trait` definition, such as expecting an instance of a specific class or its subclass (e.g., `Instance(numpy.ndarray)`).
fixAssign a value that is an instance of the required class or a subclass thereof. Example: `import numpy as np; obj.data = np.array([1, 2, 3])`.
TypeError: _my_trait_changed() takes 1 positional argument but 2 were given
A method decorated with `@on_traits_change` was defined with an incorrect signature, often missing the `self` argument or misinterpreting the number of arguments when attempting to capture `old` and `new` values.
fixEnsure the decorated method includes `self` as the first argument, and optionally `old` and `new` for the previous and current values if they are intended to be used. Example: `def _my_trait_changed(self, old, new):`
Upgrade
Version history
7.1.0latest on PyPI · released Dec 17, 2025
Audit
Dependencies
numpyoptionalTo support trait types for arrays (e.g., Array trait).
traitsuioptionalTo support GUI views and visualization features for traits.