Python dir() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Built-in

Definition

In Python, dir(obj) returns a sorted list of names: the object's attributes, its methods, and those inherited from its classes. It is a quick exploration tool in the interactive shell: dir(str) shows every string method.

Without an argument, dir() lists the names in the current scope. Classes can customize the result by defining __dir__(). The list is meant for humans, so it may not include every attribute that getattr() can find.

dir() is a built-in function: it lives in the builtins module, so it is always available without an import.

Syntax

Pass an object, or nothing for the current scope.

python
names = dir(obj)
names_here = dir()
CallWhat it does
dir(str)All string methods and special names.
"upper" in dir(str)Returns True.
[n for n in dir(x) if not n.startswith("_")]Public names only.
dir()Names in the current scope.

Most lists contain many __dunder__ names; filter them out to see the public interface.

Library declarations
python
dir()
dir(object, /)

Parameters

ParameterDescription
objectOptional. Any object: module, class, instance, value.

Return Value

Return ValueDescription
listA sorted list of strings.

Python Examples

Example 1 — Explore the Methods of str

Check the size of dir("text"), pick a few names, and test membership.

python
names = dir("text")

print(len(names) > 40)
print([n for n in names if n.startswith("is")][:4])
print("upper" in dir(str), "append" in dir(str))

How It Works

  1. Many names. Strings have dozens of attributes, so only the count is checked.
  2. Sorted list. Filtering for names that start with "is" returns them alphabetically.
  3. Type or value. dir("text") and dir(str) list the same methods.
  4. Membership. Strings have upper but no append, which belongs to lists.

Example 2 — List the Public Interface of Your Class

Hide underscore names to see data attributes and methods together.

python
class Robot:
    model = "R2"

    def __init__(self):
        self.battery = 100

    def beep(self):
        return "beep"

    def _secret(self):
        return "hidden"


r = Robot()
print([n for n in dir(r) if not n.startswith("_")])

How It Works

  1. Everything together. Instance data (battery), methods (beep), and class attributes (model) all appear.
  2. Underscores hidden. The filter drops _secret and every __dunder__ name.
  3. Inherited names. Without the filter, names from object such as __init__ would show too.
  4. Alphabetical. The result is sorted, not in definition order.

Example 3 — dir() in a Function and a Custom __dir__

Customize what dir() reports for a class and list a function's local names.

python
class Shy:
    def __init__(self):
        self.visible = 1
        self.hidden = 2

    def __dir__(self):
        return ["visible"]


def scope_demo():
    a = 1
    b = 2
    return dir()


print(dir(Shy()))
print(scope_demo())
print(hasattr(Shy(), "hidden"))

How It Works

  1. __dir__ hook. dir(Shy()) calls __dir__() and sorts what it returns.
  2. Only a listing. hidden is left out of the list, but hasattr() still finds it.
  3. No argument. Inside a function, dir() returns the local variable names.
  4. For exploring. Use dir() to discover names, not to enforce privacy.

Frequently Asked Questions

It returns a sorted list of names: an object's attributes and methods, or the names in the current scope.
dir(obj). Filter with [n for n in dir(obj) if not n.startswith("_")] for the public ones.
dir() lists names, including inherited ones. vars() returns the dict of attributes stored on the object itself.
The names defined in the current local scope.
Define __dir__(self) and return a list of names; dir() sorts it.

Next: divmod()

Quotient and remainder of a division in one call.

divmod() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

7 people found this page helpful