types-attrs (Legacy Type Stubs for attrs)

Common errors

• Mypy: error: Duplicate module 'attrs'

  cause This error occurs when both the `attrs` library (version 18.2.0 or newer with built-in types) and the `types-attrs` stub package are installed. Mypy sees two sources of type information for the `attrs` module.
  fix Uninstall the `types-attrs` package: `pip uninstall types-attrs`. Modern versions of `attrs` provide their own type annotations.

• Mypy: error: Cannot find module named 'attrs'

  cause This error can occur if `attrs` is not installed, or if `types-attrs` was installed for an older `attrs` version but `attrs` itself is missing, or if Mypy is not configured to find installed packages.
  fix Ensure the `attrs` library is installed (`pip install attrs`). If using older `attrs` where `types-attrs` was necessary, ensure both are installed. Verify your Mypy configuration to include your project's installed packages.

• AttributeError: 'MyClass' object has no attribute 'some_field_name'

  cause This typically happens when a field is declared with a type annotation but without `attrs.field()` (and `auto_attribs=True` is not set), making it a plain Python class attribute rather than an `attrs` managed attribute.
  fix To make 'some_field_name' an `attrs` attribute, either define it using `some_field_name = field(type=str)` or, for modern `attrs`, use `@define(auto_attribs=True)` on the class and define it as `some_field_name: str`.

Warnings

• breaking The `types-attrs` package is obsolete for `attrs` versions 18.2.0 and newer. The `attrs` library itself ships with type annotations, making this stub package redundant and potentially problematic if both are installed.
  Fix: Uninstall `types-attrs` if your `attrs` version is 18.2.0 or newer: `pip uninstall types-attrs`.
• gotcha If you define a class with an `attrs.field()` that lacks a type annotation, `attrs` will ignore other fields that *do* have a type annotation but are *not* defined using `attrs.field()`.
  Fix: Always annotate all attributes if you use type annotations. For fields needing advanced `attrs` features (like validators, converters, or factories), use `attrs.field()` in conjunction with type annotations. For simple attributes, `attrs.define(auto_attribs=True)` allows omitting `field()` if all attributes are type-annotated.
• gotcha Defining an attribute with only a type annotation (e.g., `x: int = 10`) without `attrs.field()` does not make it an `attrs` attribute if other fields use `attrs.field()`. Such attributes will not participate in `attrs` features like `__init__`, `__repr__`, etc.
  Fix: Either use `attrs.field()` for all attributes, or enable `auto_attribs=True` on the `@define` decorator and ensure *all* attributes are type-annotated to have `attrs` manage them. Use `typing.ClassVar` for true class-level variables that should not be part of the `attrs` instance.

Install

• pip install types-attrs Install types-attrs (for older attrs versions)

Imports

• define

  from attrs import define

  Types are provided directly by the `attrs` library for versions >= 18.2.0. You do not import directly from `types-attrs`.
• field

  from attrs import field

  Similarly, `field` is imported directly from `attrs`.

Quickstart

This quickstart demonstrates defining an `attrs` class with type annotations. Note that `types-attrs` is not imported, as the `attrs` library (version 18.2.0 and newer) provides its own type information directly. Type checkers like Mypy will pick up types from the `attrs` package itself.

import attr
from attrs import define, field
from typing import List, ClassVar

@define
class User:
    id: int = field(validator=attr.validators.instance_of(int))
    name: str = field(default='Guest')
    emails: List[str] = field(factory=list)
    
    # Correct way to define a class variable with type annotation
    CLASS_CONSTANT: ClassVar[str] = "SHARED_VALUE"

# Instantiate the class, type checkers will use annotations from `attrs`
user = User(id=123, name='Alice', emails=['alice@example.com'])
print(user)