Understanding Class and Instance Variables in Python 3

Object-oriented programming allows for variables to be used at the class level or the instance level. Variables are essentially symbols that stand in for a value you’re using in a program.

A class variable is defined inside a class but outside of any method, and it is shared by every instance of that class. An instance variable is defined inside a method (usually the __init__ constructor) using self, and each object gets its own separate copy. In short, class variables hold data that belongs to the class as a whole, while instance variables hold data that belongs to one specific object.

When we expect a variable to have the same value across instances, or when we would like to initialize a variable, we can define that variable at the class level. When we anticipate the variables will change significantly across instances, we can define them at the instance level.

One of the principles of software development is the DRY principle, which stands for don’t repeat yourself. This principle is geared towards limiting repetition within code, and object-oriented programming adheres to the DRY principle as it reduces redundancy.

This tutorial will demonstrate the use of both class and instance variables in object-oriented programming within Python. You will define class and instance variables, see how Python decides which one to read when a name exists in both places, learn how to avoid the common mutable class variable bug, compare the two kinds of variables side by side, watch how they behave under inheritance, and inspect them with __dict__ and vars(). The examples were tested with Python 3.14, the current stable release, but the behavior described applies to every modern version of Python 3.

You should have Python 3 installed and a programming environment set up on your computer or server. If you don’t have a programming environment set up, you can refer to the installation and setup guides for a local programming environment or for a programming environment on your server appropriate for your operating system (Ubuntu, CentOS, Debian, etc.)

It will also help to have a basic understanding of Python classes and objects, since class and instance variables live inside class definitions.

Class variables are defined within the class definition. Because they are owned by the class itself, class variables are shared by all instances of the class. They therefore will generally have the same value for every instance unless you are using the class variable to initialize a variable.

Defined outside of all the methods, class variables are, by convention, typically placed right below the class header and before the constructor method and other methods.

A class variable alone looks like the following:

class Shark:
    animal_type = "fish"

Here, the variable animal_type is assigned the value "fish". This is an attribute, which is simply a named value attached to an object (in this case, the class).

We can create an instance of the Shark class (we’ll call it new_shark) and print the variable by using dot notation:

class Shark:
    animal_type = "fish"

new_shark = Shark()
print(new_shark.animal_type)

Let’s run the program:

python shark.py

Running this program returns the following output:

fish

Our program returns the value of the variable.

Let’s add a few more class variables and print them out:

class Shark:
    animal_type = "fish"
    location = "ocean"
    followers = 5

new_shark = Shark()
print(new_shark.animal_type)
print(new_shark.location)
print(new_shark.followers)

Just like with any other variable, class variables can consist of any data type available to us in Python. In this program, we have strings and an integer. Let’s run the program again with the python shark.py command and review the output:

fish
ocean
5

The instance of new_shark is able to access all the class variables and print them out when we run the program.

Class variables allow us to define variables upon constructing the class. These variables and their associated values are then accessible to each instance of the class.

Instance variables are owned by instances of the class. This means that for each object or instance of a class, the instance variables are different.

Unlike class variables, instance variables are defined within methods.

In the Shark class example below, name and age are instance variables:

class Shark:
    def __init__(self, name, age):
        self.name = name
        self.age = age

The self keyword refers to the specific instance being created or used. When you write self.name = name, Python stores that value on the individual object rather than on the class, which is what makes the value unique to each instance. When we create a Shark object, we will have to define these variables, which are passed as parameters within the constructor method or another method.

class Shark:
    def __init__(self, name, age):
        self.name = name
        self.age = age

new_shark = Shark("Sammy", 5)

As with class variables, we can similarly call to print instance variables:

class Shark:
    def __init__(self, name, age):
        self.name = name
        self.age = age

new_shark = Shark("Sammy", 5)
print(new_shark.name)
print(new_shark.age)

When we run this program, we’ll receive the following output:

Sammy
5

The output we receive is made up of the values of the variables that we initialized for the object instance of new_shark.

Let’s create another object of the Shark class called stevie:

class Shark:
    def __init__(self, name, age):
        self.name = name
        self.age = age

new_shark = Shark("Sammy", 5)
print(new_shark.name)
print(new_shark.age)

stevie = Shark("Stevie", 8)
print(stevie.name)
print(stevie.age)

The highlighted lines create a second object and print its values, producing this output:

Sammy
5
Stevie
8

The stevie object, like the new_shark object, passes the parameters specific for that instance of the Shark class to assign values to the instance variables.

Instance variables, owned by objects of the class, allow for each object or instance to have different values assigned to those variables.

When you read an attribute with dot notation, such as new_shark.animal_type, Python does not look in just one place. It follows a lookup order through namespaces. A namespace is simply a mapping from names to values, and every instance and every class has its own.

Python checks the instance namespace first. If the name is found there, that value is returned. If it is not found, Python then checks the class namespace (and, during inheritance, the parent classes). The official Python tutorial on classes describes this same precedence: instance attributes take priority over class attributes with the same name.

This precedence has an important consequence. Assigning to instance.attribute always creates or updates a value in the instance namespace. It never changes the class variable, even when a class variable of the same name exists.

The following example shows an instance variable shadowing a class variable:

class Shark:
    animal_type = "fish"

new_shark = Shark()
print(new_shark.animal_type)        # reads the class variable

new_shark.animal_type = "shark"     # creates an instance variable
print(new_shark.animal_type)        # reads the new instance variable
print(Shark.animal_type)            # the class variable is unchanged

This produces the following output:

fish
shark
fish

The first print reads the class variable because the instance has no animal_type of its own yet. The assignment creates a new animal_type in the instance namespace, so the second print reads that instance value. The class variable, accessed through Shark.animal_type, still holds its original value. This is what we mean when we say an instance variable shadows a class variable: it hides the class value for that one instance without deleting or altering it.

Before choosing which kind of variable to use, it helps to see the two compared across the dimensions that matter most in real code. The following table summarizes how class variables and instance variables differ in scope, storage, and behavior.

As the table shows, the central difference is ownership: a class variable lives in one place and is seen by everyone, while an instance variable is created fresh for each object. That single distinction drives the mutability risk discussed in the next section.

One of the most frequently reported beginner mistakes in Python, involves using a mutable object such as a list or a dictionary as a class variable. Because the class variable is shared by every instance, mutating it through one object changes it for all of them.

The following example looks reasonable but contains this bug:

class Shark:
    teeth = []                    # mutable class variable shared by all instances

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

sammy = Shark("Sammy")
stevie = Shark("Stevie")

sammy.teeth.append("incisor")     # appends to the shared list
print(sammy.teeth)
print(stevie.teeth)

Calling .append() mutates the existing list in place rather than reassigning the attribute, so Python never creates a new instance variable. Both objects keep pointing at the same shared list, which produces this output:

['incisor']
['incisor']

Even though we only appended to sammy.teeth, the change appears on stevie as well, because both names refer to the one list stored on the class. This is rarely what you want.

The fix is to assign the mutable value inside __init__ so that each instance receives its own independent object:

class Shark:

    def __init__(self, name):
        self.name = name
        self.teeth = []           # each instance gets its own list

sammy = Shark("Sammy")
stevie = Shark("Stevie")

sammy.teeth.append("incisor")
print(sammy.teeth)
print(stevie.teeth)

Now each object owns a separate list, so appending to one no longer affects the other, as the output confirms:

['incisor']
[]

A useful rule of thumb is that immutable values such as strings, numbers, and tuples are usually safe as class variables, while mutable values such as lists, dictionaries, and sets often belong in __init__ when each instance should maintain its own state.

Class variables and instance variables will often be utilized at the same time, so let’s look at an example of this using the Shark class we created. The comments in the program outline each step of the process.

class Shark:

    # Class variables
    animal_type = "fish"
    location = "ocean"

    # Constructor method with instance variables name and age
    def __init__(self, name, age):
        self.name = name
        self.age = age

    # Method that accepts a followers parameter
    def set_followers(self, followers):
        print("This user has " + str(followers) + " followers")


def main():
    # First object, set up instance variables of constructor method
    sammy = Shark("Sammy", 5)

    # Print out instance variable name
    print(sammy.name)

    # Print out class variable location
    print(sammy.location)

    # Second object
    stevie = Shark("Stevie", 8)

    # Print out instance variable name
    print(stevie.name)

    # Call set_followers and pass a followers value.
    stevie.set_followers(77)

    # Print out class variable animal_type
    print(stevie.animal_type)

if __name__ == "__main__":
    main()

When we run this code, we’ll receive the following output:

Sammy
ocean
Stevie
This user has 77 followers
fish

Here, we have made use of both class and instance variables in two objects of the Shark class, sammy and stevie.

When to use a class variable instead of an instance variable

Deciding between the two comes down to a single question: does the value belong to the class as a whole, or to one specific object? Use a class variable when the value is genuinely shared, such as a constant configuration value, a default that every instance starts with, or a counter that tracks how many objects have been created. Use an instance variable when the value describes one particular object, such as its name or age.

A counter is a clear example of a value that belongs to the class rather than to any single object:

class Shark:
    total_sharks = 0              # class variable shared across all instances

    def __init__(self, name):
        self.name = name
        Shark.total_sharks += 1   # update the shared counter on every new object

sammy = Shark("Sammy")
stevie = Shark("Stevie")
print(Shark.total_sharks)

Each time the constructor runs, it increments the shared counter on the class, so the count reflects every object ever created:

2

Note that the counter is updated through Shark.total_sharks rather than self.total_sharks. Writing to self.total_sharks would create an instance variable and leave the shared count untouched, which is exactly the shadowing behavior described earlier.

Class variables participate in inheritance, which means a subclass automatically has access to the class variables defined on its parent. When you read a class variable on a subclass, Python walks the method resolution order (MRO), the ordered list of classes that Python searches, starting with the subclass and moving up to its parents.

In this example, the Hammerhead subclass does not define animal_type, so reading it falls back to the parent Shark class:

class Shark:
    animal_type = "fish"

class Hammerhead(Shark):
    pass

print(Hammerhead.animal_type)     # inherited from Shark through the MRO

Because Hammerhead has no animal_type of its own, Python finds it on Shark, producing this output:

fish

A subclass can also override a class variable by assigning the same name at the subclass level. This creates a separate class variable on the subclass that shadows the parent’s value without changing it:

class Shark:
    animal_type = "fish"

class Hammerhead(Shark):
    animal_type = "shark species"

print(Shark.animal_type)
print(Hammerhead.animal_type)

Each class now reports its own value, since the subclass variable takes precedence for Hammerhead while Shark keeps its original value:

fish
shark species

This mirrors the instance-level shadowing seen earlier, applied one level up at the class hierarchy instead of at a single object.

When you are unsure whether an attribute is stored on the instance or on the class, Python lets you inspect both namespaces directly. By default, every instance of a normal Python class has a __dict__ attribute, a dictionary that holds its own attributes, and the built-in vars() function returns that same dictionary.

The following example inspects an instance’s own attributes:

class Shark:
    animal_type = "fish"          # class variable

    def __init__(self, name, age):
        self.name = name          # instance variables
        self.age = age

sammy = Shark("Sammy", 5)
print(sammy.__dict__)
print(vars(sammy))

Both calls return the same dictionary, which contains only the instance variables and not the class variable animal_type:

{'name': 'Sammy', 'age': 5}
{'name': 'Sammy', 'age': 5}

To see the class-level attributes instead, inspect the class __dict__:

class Shark:
    animal_type = "fish"

    def __init__(self, name, age):
        self.name = name
        self.age = age

print(Shark.__dict__["animal_type"])

Reading the animal_type key from the class dictionary returns the class variable’s value:

fish

Inspecting __dict__ is a reliable way to confirm where a value actually lives, which is especially helpful when debugging the shadowing and mutable variable behavior described in the earlier sections.

Developers coming from statically typed languages such as Java or C++ often map the idea of a static field onto a Python class variable, and the comparison is a useful starting point because both belong to the class rather than to an individual object. However, Python class variables are more flexible than static fields in a few important ways.

A static field in Java or C++ is declared with the static keyword and a fixed type, and it cannot be shadowed on a per-object basis. Static fields remain associated with the class itself. In Python there is no static keyword and no type declaration, any instance can shadow a class variable simply by assigning to the same name, and class variables participate in the method resolution order during inheritance rather than being resolved strictly at compile time. The practical takeaway is that a Python class variable behaves like a shared default that any instance or subclass can quietly override, so you should not assume the same value is seen everywhere the way you might with a true static field.

1. What is the difference between a class variable and an instance variable in Python?

A class variable is defined at the class level and is shared by all instances of that class, while an instance variable is defined inside __init__ (or another method) using self and is unique to each individual object. Class variables are good for values that belong to the class as a whole, such as constants or shared counters, whereas instance variables hold per-object data such as a name or an age. The two are frequently used together in the same class.

2. Can an instance variable override a class variable in Python?

Yes. If you assign a value to an attribute on an instance that shares a name with a class variable, Python creates a new entry in that instance’s __dict__, which shadows the class variable for that instance only. The class variable itself is not modified, so other instances still see the original class value. You can confirm this by reading ClassName.attribute, which continues to return the unchanged class value.

3. When should I use a class variable instead of an instance variable?

Use a class variable when a value is truly shared across all instances and belongs to the class itself, such as a counter of how many objects have been created, a constant configuration value, or a default that all instances reference unless individually overridden. Use an instance variable for any value that should differ from one object to the next. If you find yourself questioning whether a value is shared, it usually belongs on the instance.

4. Why is using a mutable object (like a list or dict) as a class variable dangerous?

Because all instances share the same object, mutating it from one instance, for example appending to a list, affects every other instance. This is one of the most common sources of unexpected bugs in Python object-oriented code. The fix is to assign the mutable default inside __init__ so each instance gets its own independent copy, while reserving class variables for immutable values such as strings, numbers, and tuples.

5. What does self do when setting instance variables?

self refers to the specific instance being constructed or used. When you write self.name = value inside __init__, Python stores that key-value pair in the instance’s own __dict__, making it unique to that object. Without self, the assignment would create a local variable that disappears when the method returns rather than persisting on the object.

6. How do class variables behave in inheritance?

A subclass inherits class variables from its parent. If the subclass assigns a new value to that variable at the class level, it creates its own class variable that shadows the parent’s value for the subclass only. If the subclass only reads the variable, Python falls back to the parent class variable through the method resolution order (MRO), the ordered chain of classes Python searches during lookup.

7. How can I inspect what instance and class variables an object has?

Use vars(instance) or instance.__dict__ to see instance-level attributes, and ClassName.__dict__ or vars(ClassName) to see class-level attributes. Note that instance.__dict__ does not include class variables unless they have been shadowed at the instance level, which makes it a quick way to check where a particular value is actually stored.

8. Is a Python class variable the same as a static variable in Java or C++?

They are conceptually similar in that both belong to the class rather than an individual object. However, Python class variables are more flexible: they can be overridden per instance by shadowing, they participate in the MRO during inheritance, and they do not require a static keyword or explicit type declaration. Treat a Python class variable as a shared default that any instance or subclass can override rather than a fixed, compile-time constant.

In object-oriented programming, variables at the class level are referred to as class variables, whereas variables at the object level are called instance variables.

Class variables are useful for values shared across all instances, while instance variables store data unique to each object. Understanding the lookup order, the mutable class variable pitfall, and how these variables behave under inheritance will help you avoid some of the most common bugs in Python object-oriented code.

Making use of class- and instance-specific variables can ensure that our code adheres to the DRY principle to reduce repetition within code.

To continue building your object-oriented Python skills, explore these related tutorials:

• How To Construct Classes and Define Objects in Python 3
• Understanding Class Inheritance in Python 3
• How To Apply Polymorphism to Classes in Python 3
• Python super() Function
• How To Use *args and **kwargs in Python 3