dir()

The introspection escape hatch — "what can I do with this thing?"

Built-in functionPython 1.0+
Common call
dir(obj)
Returns
a sorted list of names
Replaces
staring at the docs when you just want to see what is available
Watch out
includes dunder names — filter with a comprehension if you want the "public" surface
dir([object])
→ list[str]

Parameters

NameTypeRequiredDescription
objectAnynoAny object. Without an argument, returns names in the current local scope. With an argument, returns names accessible on the object — instance attributes, class attributes, methods, inherited attributes.

Return value

list[str] — A sorted list of names. Without argument: names in the current local scope. With object: names accessible on the object (attributes and methods, including inherited). Includes dunder names like __init__.

Common patterns

Filter out dunders
The public interface — everything that does not start with __.
public = [n for n in dir(obj) if not n.startswith("_")]
Find methods only
Skip attributes, keep callables.
methods = [n for n in dir(obj) if callable(getattr(obj, n))]
Discover interactively in the REPL
The canonical "what is this?" workflow.
>>> dir(some_object)
['__class__', '__init__', ...]
For rich info, use help() instead
dir gives names; help gives docstrings and signatures.
help(obj)   # prints the type, docstring, and methods

Examples

1. str attributes
dir(str)[:5]
Returns
['__add__', '__class__', ...]
2. Filter dunders
[n for n in dir(list) if not n.startswith("_")]
Returns
['append', 'clear', 'copy', ...]
3. Current scope
dir()
Returns
["__builtins__", "__name__", ...]
4. Module
import math dir(math)
Returns
['acos', 'asin', 'atan', ..., 'pi']
5. Instance vs class
"hi".upper dir("hi")[:3]
Returns
shows both instance and class attrs

Pitfalls

1. Result includes ALL attributes — dunders too
The output can be overwhelming. Every dunder method (__init__, __repr__, __eq__, ...) appears. Filter with a comprehension when you want just the "public" API.
Overwhelming list
dir(obj)
includes ~30 dunders per object
Filter dunders
[n for n in dir(obj) if not n.startswith("_")]
public surface only
2. Sorted output — NOT source order
The result is alphabetically sorted, not in definition order. If you need declaration order, use vars() or __dict__.
Assumed source order
dir(MyClass)
alphabetical, not the class body order
Use vars()
list(vars(MyClass))
declaration order (Python 3.7+)
3. Custom __dir__ can lie
A class can override __dir__ to return a curated list. This is useful for public API design but means dir() may not show every real attribute.
Missing real attr
# obj hides "secret" from dir()
"secret" in dir(obj)
False, but hasattr(obj, "secret") is True
Check with hasattr
hasattr(obj, name)
authoritative
4. dir() with no argument uses the CURRENT scope
Not the caller's scope, not the module scope — the current local scope. Inside a function, that means local variables only.
Assumed globals
def f():
    x = 1
    return dir()
['x'] # only local x
Use globals()
def f():
    return list(globals())
module-level names

When to use

Use it
  • REPL exploration — "what methods does this have?"
  • Programmatic introspection with filtering
  • Building documentation or discovering public API
  • Debugging "why does this attribute not exist?"
Reach for something else
  • You need docstrings → help()
  • You need declaration order → vars() or __dict__
  • You need type-checked signatures → inspect.signature
  • You have a specific attribute in mind → hasattr / getattr is more direct

Notes

Complexity
O(n log n) — walks the MRO and sorts
Return
A sorted list of strings
CPython impl
Python/bltinmodule.c :: builtin_dir — calls __dir__
Memory
Allocates one list
Thread-safe
Yes for immutable class hierarchies

FAQ

Because every object inherits from object, which defines many dunders (__init__, __repr__, __eq__, ...). dir shows them all. Filter with a comprehension `[n for n in dir(x) if not n.startswith("_")]` to see just the public surface.

History

1.0
dir() has been a builtin since Python 1.0.
2.6
__dir__ hook added — classes can customize what dir() reports.