Last modified: Nov 19, 2026

Python Property Decorator Explained

The @property decorator is one of the most useful tools in Python classes. It lets you turn a method into something that looks like a normal attribute.

This keeps your code clean. You can add logic, checks, and computed values without changing how users access your data.

In this guide, you will learn what the property decorator does, why it matters, and how to use it well. We will walk through simple examples with code and output.

What Is the Property Decorator?

In Python, an attribute is a value stored on an object, like person.name. A method is a function you call, like person.show_name().

The @property decorator lets a method behave like an attribute. You access it without parentheses.

Behind the scenes, Python still runs your method. But the caller sees a plain value. This is called a getter.


class Circle:
    def __init__(self, radius):
        self.radius = radius

    @property
    def area(self):
        # Computed each time it is accessed
        return 3.14159 * self.radius ** 2

c = Circle(5)
print(c.area)   # No parentheses needed

78.53975

Notice that we wrote c.area and not c.area(). That is the magic of the property decorator.

Why Use Properties?

Properties give you control over how attributes are read, set, and deleted. Without them, you would need getter and setter methods with awkward names.

Here are the main benefits:

  • Clean syntax: users read values like normal attributes.
  • Validation: you can check values before saving them.
  • Computed values: you can calculate results on demand.
  • Backward compatibility: you can add logic later without breaking callers.

Properties also help when your class grows. If you later need to add a check, you do not have to rewrite every line that touches the attribute.

The Getter: Reading a Value

The method decorated with @property is the getter. It runs every time the attribute is read.

You can put any logic inside it. For example, you can format a value or combine several fields.


class Person:
    def __init__(self, first, last):
        self.first = first
        self.last = last

    @property
    def full_name(self):
        # Combine two fields into one value
        return f"{self.first} {self.last}"

p = Person("Ada", "Lovelace")
print(p.full_name)

Ada Lovelace

The full_name value is never stored. It is built each time you read it. This avoids data getting out of sync.

The Setter: Writing a Value Safely

To allow writing, you add a setter. Use @name.setter where name matches the property.

Setters are perfect for validation. You can reject bad input before it corrupts your object.


class Product:
    def __init__(self, price):
        self.price = price  # Calls the setter below

    @property
    def price(self):
        return self._price

    @price.setter
    def price(self, value):
        if value < 0:
            raise ValueError("Price cannot be negative")
        self._price = value

item = Product(20)
print(item.price)

item.price = 35
print(item.price)

item.price = -5  # This will fail

20
35
ValueError: Price cannot be negative

We store the real value in self._price. The underscore signals that it is internal. Users should go through price instead.

This pattern is common in Python. If you want to compare it with other function tools, our guide on Python lambda vs function key differences shows when small functions help and when a full method is better.

The Deleter: Removing a Value

You can also define a deleter with @name.deleter. It runs when someone uses del on the attribute.


class Account:
    def __init__(self):
        self._balance = 100

    @property
    def balance(self):
        return self._balance

    @balance.deleter
    def balance(self):
        print("Balance removed")
        del self._balance

acc = Account()
print(acc.balance)
del acc.balance

100
Balance removed

Deleters are less common. But they are useful when an object must clean up state or release a resource.

Read-Only Properties

If you define only the getter, the property becomes read-only. Trying to set it raises an error.


class Config:
    @property
    def version(self):
        return "1.0"

cfg = Config()
print(cfg.version)
cfg.version = "2.0"  # Not allowed

1.0
AttributeError: can't set attribute

Read-only properties are great for values that should never change from outside the class.

Properties vs Regular Attributes

A plain attribute is simple and fast. A property adds a function call behind the scenes. For most code, the small cost does not matter.

Use a property when you need logic. Use a plain attribute when you just store data.

Do not wrap every attribute in a property by default. Add one only when you need validation, computation, or control.

Common Mistakes to Avoid

Beginners often hit a few common traps. Watch out for these.

Forgetting the underscore. If your setter assigns to the same name as the property, it calls itself forever. Always use a private name like _value.

Calling the property. Remember, you access it without parentheses. Writing obj.name() on a property that returns a string will fail.

Overusing properties. Too many properties make classes hard to read. Keep them focused.

When you debug these issues, knowing how objects and values are identified helps. Our article on the Python id function and object identity explains how to check what an object really is.

Properties with Inheritance

Properties work well with inheritance. A child class can override a property or extend it.


class Animal:
    @property
    def sound(self):
        return "Some sound"

class Dog(Animal):
    @property
    def sound(self):
        return "Woof"

print(Dog().sound)

Woof

If your child class calls a parent method, the super function helps. See Python super() function explained for a clear walkthrough.

When to Use the Property Decorator

Use @property when you need to:

  • Validate values before they are stored.
  • Compute a value from other fields.
  • Keep an API stable while adding logic.
  • Expose read-only data.

Skip it when a simple attribute is enough. Simpler code is easier to maintain.

Conclusion

The Python property decorator turns methods into attribute-like values. It gives you clean syntax with full control over reading, writing, and deleting data.

Start with a simple getter. Add a setter when you need validation. Keep internal values in underscore-prefixed names.

Used well, properties make your classes safer and easier to use. Practice with small examples, and you will master them quickly.