Quick answer: self is the conventional name for the instance passed to an instance method; cls is the conventional name for the class passed to a method decorated with @classmethod. The distinction is about what receives the call, not about two special Python keywords.
In Python classes, self refers to the current instance, while cls refers to the current class. These names are conventions, but they are strong conventions that make object-oriented code easier to read.
Use self in normal instance methods that read or update data on one object. Use cls in class methods that need to work with the class itself, often to create objects or read class-level data. The official Python classes tutorial explains methods and instances, the classmethod documentation defines @classmethod, and the data model documentation covers attribute lookup.
Use self In Instance Methods
A normal method receives the object instance as its first argument. By convention, that first argument is named self.
class User:
def __init__(self, name):
self.name = name
def label(self):
return f"User: {self.name}"
user = User("Ada")
print(user.label())
The method reads self.name, which belongs to that specific object. A different User instance can have a different name.
Use self whenever the method depends on instance state.
Use cls In Class Methods
A class method receives the class as its first argument. By convention, that first argument is named cls.
class User:
def __init__(self, name):
self.name = name
@classmethod
def from_uppercase(cls, name):
return cls(name.title())
user = User.from_uppercase("ada")
print(user.name)
The method calls cls(...), so it creates an instance of the class that received the call.
Class methods are common for alternate constructors and factory-style helpers.
cls Preserves Subclasses
Using cls instead of a hard-coded class name helps subclass calls return the subclass.
class Document:
def __init__(self, title):
self.title = title
@classmethod
def blank(cls):
return cls("Untitled")
class Report(Document):
pass
item = Report.blank()
print(type(item).__name__)
The output is Report, because cls is the class used for the call. If the method had hard-coded Document, it would always create the base class.
This is one of the main reasons class methods use cls.
Use self For Object Data
Instance methods can read and update data stored on one object. That makes self the right choice for behavior tied to a single instance.
class Counter:
def __init__(self):
self.count = 0
def increment(self):
self.count += 1
return self.count
counter = Counter()
print(counter.increment())
print(counter.increment())
Each Counter object keeps its own count. Updating one instance does not update every instance.
If the method needs object-specific data, it should usually be an instance method.
Use staticmethod When Neither Is Needed
A static method receives neither self nor cls. It is namespaced inside the class but does not need instance or class state.
class Temperature:
@staticmethod
def celsius_to_fahrenheit(celsius):
return celsius * 9 / 5 + 32
print(Temperature.celsius_to_fahrenheit(20))
Use @staticmethod sparingly. If a function does not use class context, a module-level function may be simpler.
Static methods are most useful when the helper is strongly tied to the class concept.
Understand Method Binding
When you call a method through an instance, Python passes the instance automatically as the first argument.
class Greeter:
def say(self, message):
return f"{self.prefix}: {message}"
greeter = Greeter()
greeter.prefix = "Hello"
print(greeter.say("Python"))
print(Greeter.say(greeter, "Python"))
The two calls are equivalent. The instance-call form is what you normally write.
This automatic binding is why instance methods include self in the definition but not in the usual call.
Common Mistakes
The names self and cls are not reserved keywords, but changing them makes code harder to read. Python passes the first argument by position. The convention tells humans what kind of object that first argument represents.
Inheritance is where the distinction matters most. A class method that returns cls(...) respects subclasses. An instance method that reads self respects the current object’s data. Mixing those ideas can create code that works for the base class but surprises subclasses.
When choosing a method type, ask what the method needs. If it needs one object’s data, use an instance method. If it needs to construct or configure the class, use a class method. If it needs neither, consider a plain function before choosing a static method.
Keep alternate constructors small. They should prepare inputs and call cls(...), leaving normal setup in __init__. This keeps every construction path consistent.
That consistency matters when tests create objects in several ways. Every path should leave the object ready to use.
Do not name the first argument something unusual without a strong reason. Python allows it, but readers expect self and cls.
Do not use cls in an instance method just because the method appears inside a class. Use cls only when the method is decorated with @classmethod and needs the class object.
Do not use a class method when the method needs data from one instance. Use an instance method so that self points to the object being changed or read.
The practical rule is simple: use self for instance behavior, cls for class-level construction or class data, and @staticmethod only when neither context is needed.
Use self For Instance State
An instance method receives a particular object as its first argument. Use self to read or update that object’s attributes and to call other instance methods. Each instance can therefore carry different state while sharing the same method implementation.
Use cls For Class-Level Construction
A classmethod receives the class that was used for the call, including a subclass when invoked through that subclass. This makes @classmethod useful for alternate constructors, parsing helpers, and factories that should return the appropriate derived type.
Preserve Subclass Behavior
Calling a classmethod through a subclass passes that subclass as cls, while hard-coding the base class inside the method can discard polymorphic behavior. Prefer cls(…) when the method is intended to construct the receiving type, and test a subclass explicitly.
Recognize Method Binding
Python binds an instance method to an object and a classmethod to a class. The decorator changes what is supplied automatically; it does not make ordinary data class-level or remove the need to define a clear API.
Use staticmethod Only When Appropriate
A staticmethod receives neither self nor cls. It is useful for a helper that is namespaced under a class but does not depend on instance or class state. If a function needs either context, using staticmethod merely hides the dependency and makes the API less clear.
The official classmethod documentation and staticmethod documentation define binding behavior. The Python classes tutorial explains instance methods and class objects. Related guidance includes subclass tests.
For related object design, compare nested classes, classes and modules, and subclass tests when choosing the right method binding.
Frequently Asked Questions
What is the difference between self and cls in Python?
self refers to a particular instance in an instance method, while cls refers to the receiving class in a classmethod.
When should I use @classmethod?
Use it for alternate constructors, class-level configuration, or behavior that should preserve the receiving subclass.
Can I name self or cls something else?
Python does not require those exact names, but using self and cls follows the standard convention and makes method intent clear.
When should I use @staticmethod?
Use staticmethod when the operation belongs conceptually to the class but needs neither an instance nor the receiving class.
