Instance vs Class Variables

The Anatomy of Instance Variables

Instance variables are defined within the __init__ method using the 'self' keyword. When you create an object, Python allocates a unique namespace for that instance, allowing it to store its own distinct values for those variables. This ensures that when you modify an instance variable on one object, it does not affect any other object created from the same class. The 'self' prefix essentially acts as a pointer, binding the data to the specific memory address of that individual instance. Because every object carries its own data set, instance variables are the primary mechanism for maintaining the unique internal state of your objects. Without them, it would be impossible to represent distinct items like different user profiles or unique bank account balances, as each entity would overwrite the data of the others upon modification.

class User:
    def __init__(self, username):
        # 'self.username' is an instance variable
        self.username = username

user1 = User('Alice')
user2 = User('Bob')
# Each object maintains its own unique state
print(user1.username)  # Output: Alice
print(user2.username)  # Output: Bob

Defining Class Variables

Class variables are defined directly inside the class body, outside of any methods. Unlike instance variables, these are tied to the class object itself rather than individual instances. When you define a variable at this scope, it becomes a shared attribute that all instances of the class can access. This is incredibly efficient when you have a piece of data that should be consistent for every object created from that class. Since the variable is stored in one location, memory is conserved because you are not duplicating the same information across thousands of objects. If you find yourself hardcoding the same configuration values inside multiple instance initializers, moving that data to a class variable is the standard approach to reduce redundancy and ensure global consistency across your object instances.

class Server:
    # 'connection_limit' is a class variable shared by all instances
    connection_limit = 100

    def __init__(self, host):
        self.host = host

s1 = Server('192.168.1.1')
s2 = Server('192.168.1.2')
# Both access the shared class variable
print(s1.connection_limit)  # Output: 100
print(s2.connection_limit)  # Output: 100

Understanding the Lookup Mechanism

Python's attribute resolution mechanism is designed to be intuitive but requires careful attention. When you attempt to access an attribute on an instance, Python first looks for it within the instance's own dictionary. If the name is not found there, Python moves up to the class dictionary to check for the attribute. This inheritance-like lookup is why class variables appear to be available on instances. However, this lookup is read-only when accessed through an instance. If you try to assign a value to an attribute that shares the name of a class variable using the instance reference, Python will create a new instance variable that shadows the class variable. The original class variable remains unchanged, and only that specific instance will now have its own unique value, effectively masking the class-wide default for that single object.

class Configuration:
    mode = 'production'

app = Configuration()
# Accessing class variable via instance
print(app.mode)  # Output: production

# Creating an instance-specific override
app.mode = 'development'
print(app.mode)  # Output: development
# The class itself remains unchanged
print(Configuration.mode)  # Output: production

The Hazards of Mutable Class Variables

A common trap when working with class variables is using mutable types like lists or dictionaries. Because class variables are shared across all instances, any modification to a mutable object stored as a class variable reflects across all instances simultaneously. If one object appends a value to a list stored in a class variable, that value becomes visible to every other object. This behavior can lead to subtle, difficult-to-track bugs where state 'leaks' between unrelated objects. To avoid this, always initialize mutable data structures inside the __init__ method as instance variables unless the intent is explicitly to maintain a shared log or registry across all instances of the class. Recognizing this distinction is vital for writing robust, predictable code that behaves reliably as your program scales in complexity and size.

class TaskRegistry:
    # DON'T do this if you want unique lists per instance
    tasks = []

worker1 = TaskRegistry()
worker2 = TaskRegistry()
worker1.tasks.append('Fix Bug')

# Both see the change because they share the same list reference
print(worker2.tasks)  # Output: ['Fix Bug']

Best Practices for Implementation

To maintain clean code, apply a simple rule: use instance variables for state, and class variables for constants or configuration. When you need to define a class variable, name it clearly to indicate it belongs to the class scope, often using uppercase if it represents a constant. If you find yourself needing to modify a class variable, do so via the class name itself rather than through an instance. This makes your intent explicit to other developers and avoids the accidental shadowing mentioned earlier. By keeping the modification logic focused on the class level, you maintain clear boundaries between global class data and individual instance data. Consistently following these patterns ensures that your object-oriented designs remain maintainable, scalable, and free from the confusion caused by mixed-scope attribute modifications during the execution of your application's logic.

class DatabaseConnection:
    TIMEOUT = 30  # Conventionally capitalized constant

    def __init__(self, db_name):
        self.db_name = db_name

# Modifying the class variable correctly
DatabaseConnection.TIMEOUT = 60
print(DatabaseConnection.TIMEOUT)  # Output: 60

Interview questions

All Python interview questions →

Check yourself

Take the full Python quiz →