What __all__ Means in Python: A Beginner-Friendly Guide

By the end of this page, you will understand what __all__ means in Python, why it is commonly used in __init__.py files, how it affects from module import *, and when you should or should not use it in real projects.

__all__ is a special Python variable used to define a module's public interface.

It is usually a list of strings:

__all__ = ["name1", "name2", "name3"]

Each string is the name of a variable, function, class, or submodule that Python should treat as publicly exportable.

The main place where __all__ matters is this kind of import:

from mymodule import *

If mymodule defines __all__, then only the names listed in __all__ are imported.

If mymodule does not define __all__, then import * usually imports all names that do not start with an underscore.

Why this matters

In real programs, a module may contain:

• public functions you want other developers to use
• helper functions meant to stay internal
• constants, classes, and implementation details

__all__ lets you say:

• "These names are part of the public API"
• "Everything else is internal"

This is especially useful in because packages often re-export selected names from submodules.

Think of a Python module like a shop.

• Everything inside the shop exists.
• But the shop window shows only selected items.
• __all__ is the list of items placed in the window.

When someone does:

from shop import *

They only get what is displayed in the window.

Without __all__, Python makes a best guess and usually shows everything that does not begin with _.

So __all__ is like a curated display of the names a module wants to present publicly.

The basic syntax is:

__all__ = ["name1", "name2"]

Example 1: Module-level __all__

# tools.py

def greet(name):
    return f"Hello, {name}!"


def add(a, b):
    return a + b


def _debug_message():
    return "debug info"


__all__ = ["greet", "add"]

Now:

from tools import *

print(greet("Sam"))
print(add(2, 3))

The names greet and add are imported, but _debug_message is not.

Example 2: Without

Consider this file:

# helpers.py

def public_function():
    return "I am public"


def another_public_function():
    return "Me too"


def _internal_function():
    return "I am internal"


__all__ = ["public_function"]

Now run:

from helpers import *

Step by step:

1. Python loads the helpers module.

2. It sees three function names:

   • public_function
   • another_public_function
   • _internal_function

3. It also sees:

   __all__ = ["public_function"]
   

4. Because __all__ exists, Python uses that list for .

1. Creating a clean package API

A package may have many internal files, but you want users to import from one simple place.

from mypackage import connect, disconnect

You can re-export those names in __init__.py and define them in __all__.

2. Hiding helper functions from wildcard imports

A module may contain utility code that should not appear as part of the public API.

def process_data(data):
    ...


def _normalize(data):
    ...

Using __all__ helps ensure only intended names are exposed with import *.

3. Building libraries for other developers

If you are writing a reusable package, __all__ helps communicate which names are stable and meant for external use.

4. Organizing large codebases

Larger projects often split features into submodules, then expose a small curated API at the package level.

5. Improving readability in interactive use

In notebooks or REPL sessions, wildcard imports are sometimes used for convenience. makes those imports more controlled.

In real codebases, __all__ is most often used as part of API design, not as a daily feature in every file.

Common patterns

Re-exporting selected names

# package/__init__.py
from .client import Client
from .errors import APIError
from .utils import format_date

__all__ = ["Client", "APIError", "format_date"]

This creates a cleaner package surface.

Separating public and internal helpers

def parse_config(path):
    ...


def _read_file(path):
    ...


__all__ = ["parse_config"]

Stabilizing a library API

Developers may change internal functions freely while trying to keep the names in __all__ stable for users.

Patterns often used alongside __all__

• Underscore prefixes like _helper for internal names

Mistake 1: Thinking __all__ makes things private

Broken assumption:

__all__ = ["public_function"]

Some beginners think this prevents access to other names. It does not.

This still works:

from helpers import _internal_function

Avoid it

Treat __all__ as a public API hint and wildcard import control, not security.

Mistake 2: Forgetting that strings must match real names

Broken code:

def greet():
    return "hi"

__all__ = ["great"]

great is misspelled. The export list should contain actual names.

Correct version:

def greet():
    return "hi"

__all__ = ["greet"]

Mistake 3: Using everywhere

__all__ vs underscore prefix

__all__ = ["name1", "name2", "name3"]

Quick rules

• __all__ is a list of strings.
• It defines the public names for from module import *.
• It is commonly used in __init__.py.
• It does not make names private.
• Without __all__, import * usually imports names that do not start with _.

Typical example

# mymodule.py

def public_func():
    pass


def _helper():
    pass


__all__ = ["public_func"]

Best practice

• Use __all__ when designing a clear public API.
• Prefer explicit imports in normal code.
• Use _name for internal helpers by convention.

Common edge cases

What is __all__ used for in Python?

It defines which names are exported when someone uses from module import *.

Does __all__ make functions private?

No. It does not enforce privacy or security. It only affects wildcard imports and documents intended public names.

Why is __all__ often placed in __init__.py?

Because packages use __init__.py to expose a clean top-level API and re-export selected names from internal modules.

Do I need __all__ in every Python file?

No. It is helpful when you want to define a clear public API, especially in reusable modules and packages.

What happens if __all__ is missing?

With from module import *, Python usually imports names that do not start with _.

Should I use from module import *?

Usually no. Explicit imports are clearer and easier to maintain.

Can __all__ include classes and constants too?

Yes. It can include any publicly exported names, such as functions, classes, constants, or submodules.

• __init__.py — Related because __all__ is commonly defined there for packages.
• Python imports — Related because __all__ directly affects import behavior.
• Modules and packages — Related because __all__ defines the public interface of a module or package.
• Wildcard imports — Related because __all__ mainly controls from module import *.
• Leading underscore naming convention — Related because names starting with _ are usually considered internal.
• Public API design — Related because __all__ helps define what other developers should use.
• Explicit imports — Related because they are the common alternative to wildcard imports.