Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Class Attributes: How They Work and Common Mistakes

Understand how Python class attributes behave, how they differ from instance attributes, and where they commonly cause bugs in real code.

~4 min readPython
#Python#class attributes#instance attributes#OOP
Illustration of Python class attributes with shared and instance-specific data

In Python, a class attribute is a variable defined directly in the class body. It is shared by every instance of that class unless an instance assigns its own value to the same name. This sharing behavior is a frequent source of bugs, especially when the attribute is mutable. Understanding how class attribute lookup works is essential for writing predictable object-oriented code.

python
class Counter: count = 0 c1 = Counter() c2 = Counter() print(c1.count) # 0 print(c2.count) # 0

Both c1 and c2 see the same count value because neither instance has its own count attribute. The attribute exists on the class, and both instances reference it through their class.

Class Attributes vs Instance Attributes

The distinction is straightforward: a class attribute belongs to the class object itself, while an instance attribute belongs to a specific instance. You define a class attribute inside the class body, outside any method. You create an instance attribute by assigning to self inside a method or by assigning directly on an instance.

python
class User: role = "guest" # class attribute def __init__(self, name): self.name = name # instance attribute u1 = User("alice") u2 = User("bob") print(u1.role) # guest print(u2.role) # guest print(u1.name) # alice print(u2.name) # bob

role is the same object for all instances. name is unique per instance. This difference matters when you mutate the attribute.

How Attribute Lookup Works

When you access an ordinary attribute on an instance, Python resolves it in a defined order. First, it checks the instance's __dict__, which holds instance-specific attributes. If the name is not found there, it checks the class's __dict__, then the base classes in method resolution order. This lookup order explains why assigning an instance attribute with the same name shadows the class attribute.

python
class Config: timeout = 30 c = Config() print(c.timeout) # 30, from class c.timeout = 60 # creates an instance attribute print(c.timeout) # 60, from instance print(Config.timeout) # 30, class attribute unchanged

The assignment c.timeout = 60 does not modify the class attribute. It creates a new entry in c.__dict__. From that point on, c.timeout returns the instance value, while other instances still see the class value.

The Mutable Class Attribute Trap

A class attribute that is a mutable object, such as a list or dictionary, is shared by all instances. If you modify the object in place, every instance sees the change. This is often unintentional.

python
class ShoppingCart: items = [] # shared mutable class attribute cart1 = ShoppingCart() cart2 = ShoppingCart() cart1.items.append("apple") print(cart2.items) # ['apple']

Both carts share the same list. To give each cart its own list, you must assign the list in __init__ as an instance attribute.

python
class ShoppingCart: def __init__(self): self.items = [] cart1 = ShoppingCart() cart2 = ShoppingCart() cart1.items.append("apple") print(cart2.items) # []

The same principle applies to any mutable class attribute, such as a list, dict, or set. This is why mutable class attributes are usually a design mistake unless the sharing is intentional.

Overriding Class Attributes on Instances

You can override a class attribute per instance by assigning to the same name on the instance. This is a common pattern for customizing behavior without affecting the class or other instances.

python
class Animal: sound = "generic" dog = Animal() dog.sound = "bark" print(dog.sound) # bark print(Animal.sound) # generic

The override only affects dog. Other instances still see the class value. This pattern is useful when you need a default value but want to allow per-instance customization.

Class Attributes and Inheritance

Class attributes are inherited by subclasses. If a subclass defines an attribute with the same name, it overrides the parent's attribute for that subclass and its instances. This allows you to define defaults in a base class and refine them in derived classes.

python
class Vehicle: wheels = 4 class Motorcycle(Vehicle): wheels = 2 print(Vehicle.wheels) # 4 print(Motorcycle.wheels) # 2

Instances of Motorcycle see 2, while instances of Vehicle see 4. The lookup order respects the subclass's own class attribute before falling back to the base class.

When to Use Class Attributes

Class attributes are appropriate for values that are genuinely shared across all instances, such as constants, configuration defaults, or counters that track the total number of instances. They also save memory because the value is stored once on the class, not duplicated per instance.

python
class ConnectionPool: max_connections = 10 active_connections = 0 def __init__(self): ConnectionPool.active_connections += 1

Here max_connections is a constant, and active_connections tracks a global count across all instances. This works because the attribute is shared and the increment is intentional.

Avoid class attributes for values that should be unique to each instance, especially if they are mutable. For per-instance state, always assign in __init__ using self.

Performance and Memory Considerations

Class attributes are stored once on the class object, so they use less memory than instance attributes when many instances exist. However, attribute lookup on an instance first checks the instance dictionary, then the class. The extra lookup is usually not a performance bottleneck.

The more significant concern is unintended sharing of mutable class attributes. If multiple threads or concurrent tasks modify the same mutable object, you can get race conditions or corrupted state. Even in single-threaded code, the shared state can lead to surprising behavior that is difficult to debug.

For values that should be shared across all instances, class attributes are efficient. For anything that might vary per instance, using instance attributes avoids accidental coupling and makes the object's state explicit.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.