Quick answer: __all__ is a sequence of strings that controls which names a module exports for a wildcard import. It can document a public API and support package re-exports, but it is not a privacy boundary and explicit imports remain clearer in most application code.
Python __all__ is a module-level list of public names. It controls what gets imported when another module uses from module import *. It is most useful when a module has helper names that should stay internal while a smaller set of functions, classes, or constants should be exported.
Most production code should prefer explicit imports such as from tools import load_config. Still, __all__ is valuable for package APIs, compatibility layers, and modules that intentionally support wildcard imports for interactive use.
If __all__ is missing, wildcard import skips names that start with an underscore and imports other public names. If __all__ exists, Python uses that list exactly. Names listed there must exist, or the import will fail.
Think of __all__ as an export contract. It tells readers, tools, and import statements which names are meant for public use. It does not make private helpers inaccessible; it only controls wildcard import behavior and documents intent.
The official Python package import documentation, import statement reference, packages tutorial, importlib documentation, and Python Packaging project tutorial are useful references.
Define __all__ In A Module
Place __all__ near the top of the module and list the public names as strings.
__all__ = ["load_config", "ConfigError"]
class ConfigError(Exception):
pass
def load_config(path):
return {"path": path}
def _parse_line(line):
return line.strip()
In this module, wildcard import exposes load_config and ConfigError. The helper _parse_line remains internal.
Keep the list explicit when the public API is small. An explicit list is easy to review during refactors and makes accidental exports less likely.
Wildcard Import Uses __all__
When code uses from settings import *, Python checks whether the target module defines __all__.
from settings import *
config = load_config("app.toml")
print(config)
try:
raise ConfigError("missing option")
except ConfigError as error:
print(error)
This style is uncommon in application code, but it appears in package initialization files, examples, and interactive sessions.
Explicit imports remain clearer for most code reviews. Use wildcard imports only when the module was designed for that style and the exported names are intentionally curated.
Use __all__ In __init__.py
A package can re-export selected names from submodules in __init__.py.
from .readers import CsvReader
from .writers import JsonWriter
__all__ = ["CsvReader", "JsonWriter"]
This lets users import from the package root while the implementation stays split across submodules.
A package root can become a stable facade. You can reorganize internal files later while keeping public imports such as from readers import CsvReader stable for users.
Keep __all__ Synchronized
If a name appears in __all__, make sure it exists in the module namespace.
__all__ = ["add", "subtract"]
def add(left, right):
return left + right
def subtract(left, right):
return left - right
missing = [name for name in __all__ if name not in globals()]
print(missing)
A small check like this can catch stale export names after refactors.
Run a check like this in tests for packages with a public API. It catches misspellings and deleted names before users hit import errors.
Hide Internal Names
Leading underscores are still useful for internal helpers, even when __all__ is present.
__all__ = ["format_title"]
def format_title(text):
return _clean(text).title()
def _clean(text):
return " ".join(text.split())
The underscore communicates intent to readers and tooling. __all__ makes the exported API explicit.
Do not put internal helpers in __all__ just because another module needs them once. Prefer a better public helper or an explicit internal import in the rare case where it is truly needed.
Build __all__ Carefully
For small modules, a literal list is clearest. If you generate the list, keep the rule easy to audit.
def area(radius):
return 3.14159 * radius * radius
def circumference(radius):
return 2 * 3.14159 * radius
def _debug_radius(radius):
return f"radius={radius}"
__all__ = [name for name in globals() if not name.startswith("_")]
Generated export lists can accidentally include imported helper names. Review them carefully before using that style in a public package.
Literal lists are usually better for libraries because they avoid surprises. Generated lists are more acceptable for small scripts or modules where the export rule is simple and tested.
Fix Checklist
Use __all__ when a module or package has a clear public API. Keep the list short, explicit, and close to the names it exports.
Do not rely on __all__ for access control. It guides wildcard imports and API clarity, but users can still import other module names directly if they know them.
After changing __all__, test one explicit import and one wildcard import in a small script. That confirms the package exposes the names you intended and nothing important was left out.
Also update documentation examples when exports change. Import examples in docs often become the first place users notice a broken public API.
For long-lived packages, review __all__ during releases. A stable export list helps users upgrade with fewer import surprises and clearer migration notes for future maintainers too.
Control Wildcard Exports
When a caller uses from module import *, Python uses __all__ to determine the names imported. Names listed there must be available in the module when the import executes.
Use It As API Documentation
A deliberate export list tells users which symbols are supported and can keep helper imports out of wildcard namespaces. Keep the list close to the module’s public API definition.
Re-export Package Names
A package initializer can import selected classes and functions from submodules and list them in __all__. This creates a stable top-level import path while implementation modules evolve behind it.
Do Not Treat It As Security
__all__ does not prevent explicit access to other names and does not hide source code, credentials, or behavior. Use real access controls and avoid placing secrets in importable modules.
Prefer Explicit Imports
Explicit imports communicate dependencies and avoid wildcard collisions. Use __all__ when the module genuinely offers a public export contract, not as a substitute for naming discipline.
Test Public Surface
Test wildcard behavior when supported, explicit re-exports, missing names, circular imports, package initialization, and documentation examples. Assert that supported names remain importable after refactors.
Use the official Python modules documentation for import and package behavior. Related Python Pool references include tests and module metadata.
For maintainable module APIs, compare public-import tests, namespace configuration, and package diagnostics before defining __all__.
Frequently Asked Questions
What is Python __all__?
It is a sequence of strings naming the public symbols exported by a module for from module import * behavior.
Does __all__ hide private names?
It controls wildcard exports, but names remain accessible through explicit imports or module attributes unless other boundaries apply.
Can a package use __all__?
Yes. A package or module can define exports and re-export selected names to present a stable public API.
Should every Python file define __all__?
No. Use it when a module has a deliberate public surface, re-exports names, or needs predictable wildcard-import behavior; explicit imports are usually clearer.
