Python · OOP · Methods

What `@classmethod` Means in Python

A practical guide to what it does, why cls matters, and when to use it

Core idea

A class method belongs to the class itself, not to one particular instance.

Key parameter

cls points to the class, which is why class methods work well with inheritance.

Most common use

Alternative constructors are usually the clearest everyday use of @classmethod.

Introduction

Python gives you several ways to define methods inside a class. One of them is @classmethod.

At first glance, it looks like just another decorator. But it solves a specific problem: sometimes a method belongs to the class itself, not to one particular object created from that class.

This guide explains what @classmethod does, how it differs from ordinary methods, and when it is actually the right tool.

Definition

What Is `@classmethod`?

@classmethod is a Python decorator that turns a method into a class method.

A class method receives the class itself as its first argument. By convention, that first argument is named cls.

Basic example:

class MyClass:
    @classmethod
    def show_class(cls):
        return cls

If you call MyClass.show_class(), Python automatically passes MyClass in as cls.

Plain English A class method works with the class itself, not with one specific instance.

Comparison

Instance Method vs Class Method

The easiest way to understand @classmethod is to compare it to an ordinary instance method.

Instance method

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

    def speak(self):
        return f"{self.name} says woof"

Here, speak() is an instance method. It works on one specific dog, so it receives self.

Class method

class Dog:
    species = "Canine"

    @classmethod
    def get_species(cls):
        return cls.species

Here, get_species() is a class method. It works with data attached to the class itself, so it receives cls.

self means one specific object. cls means the class that created the object.

Why cls matters

Why `cls` Matters

This is the part that makes @classmethod worth learning.

If a class method creates a new object, it should usually use cls(...) instead of hardcoding the class name.

Example:

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

    @classmethod
    def from_birth_year(cls, name, birth_year, current_year):
        age = current_year - birth_year
        return cls(name, age)

This method gives you another way to create a Person. Instead of supplying age directly, you supply a birth year.

The key detail is return cls(name, age). That means the method uses whichever class it was called on.

That becomes especially important with inheritance.

Inheritance

Why `@classmethod` Works Well with Inheritance

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

    @classmethod
    def from_birth_year(cls, name, birth_year, current_year):
        return cls(name, current_year - birth_year)


class Employee(Person):
    pass


employee = Employee.from_birth_year("Raell", 1995, 2026)

Because the method uses cls, calling it on Employee creates an Employee, not just a Person.

Why this matters If you hardcode Person(...) instead of using cls(...), inheritance becomes less flexible.

Common uses

Common Uses for `@classmethod`

1. Alternative constructors

This is the most common use.

class Rectangle:
    def __init__(self, width, height):
        self.width = width
        self.height = height

    @classmethod
    def create_square(cls, side_length):
        return cls(side_length, side_length)

Here, create_square() is just a cleaner way to build a rectangle with equal sides.

2. Accessing class-level state

class MyClass:
    count = 0

    def __init__(self):
        MyClass.count += 1

    @classmethod
    def get_count(cls):
        return cls.count

Since count belongs to the class, a class method is a natural place to access it.

3. Polymorphic behavior in subclasses

class Vehicle:
    @classmethod
    def description(cls):
        return "This is a vehicle."


class Car(Vehicle):
    @classmethod
    def description(cls):
        return "This is a car."


class Bicycle(Vehicle):
    pass

Subclasses can override class methods just like ordinary methods.

When to use it

When to Use `@classmethod`

Use @classmethod when:

the method needs the class, not a specific object
you want an alternative constructor
you need subclass-friendly object creation through cls(...)
you are working with class-level state

Do not use @classmethod when the method really depends on one object’s instance data. That is what ordinary instance methods are for.

Related confusion

`@classmethod` vs `@staticmethod`

This is another place people get confused.

Instance method: gets self
Class method: gets cls
Static method: gets neither

A static method is just a function placed inside the class namespace. It does not automatically receive the object or the class.

class MathTools:
    @staticmethod
    def add(a, b):
        return a + b

If the method needs the class, use @classmethod. If it needs neither the class nor the instance, @staticmethod may be a better fit.

FAQ

Frequently Asked Questions

These are the practical questions beginners usually have when @classmethod first starts to make sense.

What does `@classmethod` do in simple terms?

It turns a method into one that receives the class itself instead of one specific instance.

Why is the first parameter called `cls`?

By convention, cls means “the class,” just as self means one instance.

What is the most common real use of `@classmethod`?

Alternative constructors are the most common use, especially methods like from_birth_year() or from_string().

Why use `cls(...)` instead of hardcoding the class name?

Because cls(...) keeps the method flexible for subclasses, which is one of the biggest practical benefits of class methods.

Can a class method access class attributes?

Yes. That is one of the natural places to use a class method, since class attributes belong to the class rather than one object.

Should I use `@classmethod` for instance-specific data?

No. If the method depends on one object’s state, an ordinary instance method with self is usually the right choice.

How is `@classmethod` different from `@staticmethod`?

A class method receives cls. A static method receives neither cls nor self.

What is the easiest way to remember when to use it?

Use @classmethod when the method is about the class as a whole, not one particular object.

Conclusion

@classmethod is not just a syntax feature. It exists for methods that belong to the class as a whole rather than to one particular object.

Its most practical use is building alternative constructors that use cls(...), which keeps your code flexible and inheritance-friendly.

The simplest way to remember it is this:

self means “this object”
cls means “this class”

Once that distinction clicks, @classmethod becomes much easier to use correctly.

Raell Dottin's Technical Blog