Python self vs cls: Instance and Class Methods
Understand the difference between self and cls in Python: instance methods receive the instance, class methods receive the class, and static methods receive neither.

Python distinguishes instance methods from class methods by how the method is defined: an ordinary method receives the instance on which it is called, while a method decorated with @classmethod receives the class. By convention, the first parameter is named self for an instance method and cls for a class method. This distinction between self and cls determines what the method can access and how it behaves under inheritance.
What self and cls Actually Bind To
An ordinary method receives the instance as its first argument. A method decorated with @classmethod receives the class object, not an instance. The parameter names are conventions, not keywords; what matters is whether the method is a plain function or decorated with @classmethod.
class Example:
def instance_method(self):
return self
@classmethod
def class_method(cls):
return clsWhen you call Example().instance_method(), Python passes the instance as self. When you call Example.class_method(), Python passes the Example class itself as cls. Python only cares about the first position because the binding step has already supplied the argument; using a different name still works, but self and cls are so universal that deviating from them makes code harder to read.
Instance Methods: Working with self
An instance method receives the instance as its first argument. Through self, the method can read and modify instance attributes, call other instance methods, and access the instance's __dict__.
class Account:
def __init__(self, owner: str, balance: float):
self.owner = owner
self.balance = balance
def deposit(self, amount: float) -> None:
self.balance += amount
def describe(self) -> str:
return f"{self.owner}: {self.balance}"The deposit method modifies self.balance, which is per-instance state. Two different Account objects hold independent balance values. If you called deposit without an instance, Python would require you to pass one explicitly: Account.deposit(account, 50.0).
Class Methods: Working with cls
A class method receives the class itself as its first argument. It cannot access instance attributes because no instance exists. It can read and modify class attributes, and it can call other class methods.
class Config:
defaults = {"timeout": 30, "retries": 3}
@classmethod
def get_default(cls, key: str):
return cls.defaults.get(key)
@classmethod
def with_timeout(cls, timeout: int):
config = cls()
config.timeout = timeout
return configThe get_default method reads from cls.defaults, which is shared across all instances. The with_timeout method is an alternative constructor: it creates an instance through cls() and configures it. Using cls() instead of Config() matters when a subclass inherits this method, because cls will be the subclass, not Config.
How Python Performs the Binding
The binding behavior comes from the descriptor protocol. When you access instance.method, Python finds the corresponding object on the class and calls its __get__ method. For a plain function, the binding produces a bound method where the instance is passed as the first argument. For a class method, the binding passes the class instead.
account = Account("Ada", 100.0)
bound = account.describe
print(bound()) # "Ada: 100.0"The function object describe itself never receives the instance automatically; the binding step does that work. This is why accessing the method on the class rather than the instance requires an explicit argument: Account.describe(account).
The Role of @staticmethod
A static method receives neither self nor cls. It behaves like a plain function that happens to live inside a class namespace. Use it when the method does not need class or instance state.
class MathUtils:
@staticmethod
def clamp(value: float, low: float, high: float) -> float:
return max(low, min(value, high))Static methods are still inherited, but the subclass does not replace the class argument. If you need polymorphic behavior—where the method should know which subclass called it—use a class method instead.
Choosing Between self and cls
The decision depends on what the method needs to access:
| Need | Parameter | Example |
|---|---|---|
| Read or modify instance state | self | Update a field, call another instance method |
| Read or modify class state | cls | Change a default, track instance count |
| Create an instance with custom setup | cls | Alternative constructor |
| Neither class nor instance state | none | Utility function inside a class |
Use self when the method's behavior depends on the specific instance's data. Use cls when the behavior is the same for the whole class, especially for factory methods or operations on class-level attributes. If a method touches neither, consider whether it belongs in the class at all; a module-level function is often clearer.
Inheritance and cls in Practice
The most important difference between self and cls appears under inheritance. A class method defined on a base class receives the subclass when called through the subclass.
class Base:
@classmethod
def create(cls):
return cls()
class Child(Base):
pass
child = Child.create()
print(type(child)) # <class '__main__.Child'>Here cls is Child, not Base. If create had used Base() directly, it would return a Base instance even when called on Child. This is why alternative constructors should use cls rather than the hardcoded class name.
The same polymorphism applies to instance methods through self: self is always the actual instance, even when the method is defined on a parent class.
Common Mistakes and Edge Cases
One frequent error is defining a class method without the @classmethod decorator and expecting cls to be passed. Without the decorator, the method is an ordinary method: when called on an instance, the first argument receives the instance instead of the class. When called on the class, no automatic binding happens, so the caller must pass the class explicitly.
Another mistake is using cls to access instance attributes. Since no instance exists, cls.attr looks up a class attribute, and AttributeError is raised if it does not exist.
Naming the first parameter something other than self or cls works syntactically but breaks the convention. Tools, linters, and other developers rely on those names to understand what the method expects.
Maintainability Implications
Class methods give you a clean way to expose alternative constructors and class-level operations without requiring an instance. They also make code easier to test in isolation because they do not depend on instance setup. Instance methods, on the other hand, are the right choice when the method's output depends on the instance's state.
A common design pattern is to use a class method as a factory and an instance method for behavior:
class Order:
def __init__(self, items: list[float]):
self.items = items
@classmethod
def from_line(cls, line: str) -> "Order":
return cls([float(item) for item in line.split(",")])
def total(self) -> float:
return sum(self.items)The factory from_line uses cls so subclasses return instances of the subclass. The total method uses self because it needs the instance's items. Keeping this separation makes the class's contract explicit and avoids surprising behavior when the class is subclassed.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.