I see __all__
in __init__.py
files. What does it do?

- 24,552
- 19
- 101
- 135

- 16,849
- 3
- 20
- 19
10 Answers
Linked to, but not explicitly mentioned here, is exactly when __all__
is used. It is a list of strings defining what symbols in a module will be exported when from <module> import *
is used on the module.
For example, the following code in a foo.py
explicitly exports the symbols bar
and baz
:
__all__ = ['bar', 'baz']
waz = 5
bar = 10
def baz(): return 'baz'
These symbols can then be imported like so:
from foo import *
print(bar)
print(baz)
# The following will trigger an exception, as "waz" is not exported by the module
print(waz)
If the __all__
above is commented out, this code will then execute to completion, as the default behaviour of import *
is to import all symbols that do not begin with an underscore, from the given namespace.
Reference: https://docs.python.org/tutorial/modules.html#importing-from-a-package
NOTE: __all__
affects the from <module> import *
behavior only. Members that are not mentioned in __all__
are still accessible from outside the module and can be imported with from <module> import <member>
.

- 14,854
- 11
- 100
- 103

- 19,639
- 4
- 30
- 24
-
@BhanuTez exactly. So `print(baz)` prints something like `
` whereas `print(baz())` prints `baz` – John Cole May 31 '20 at 22:35 -
24The goal is to illustrate that the symbols are exported. Whether it executes the function or not is secondary. – Alec Thomas Jul 22 '20 at 04:29
-
71I find it puzzling that to this day, there isn't a way to populate `__all__` by referencing the functions/objects directly. Instead we have to type down their names and correct them individually anytime a name changes. Seems very bug prone for active codebases. – Julio Cezar Silva Aug 07 '20 at 15:01
-
20@JulioCezarSilva off topic a bit, but worth noting that for classes and functions you can use the `__name__` property – phsyron Sep 29 '20 at 17:45
-
2@phsyron While tour suggestion seems legit, doesn't it require the modules to already be imported? I ask because by populating `__all__` this way I still get a warning about implicit imports from mypy, and by typing explicitly I don't. – Yair M Sep 16 '21 at 06:59
-
@YairM I'm not sure I understand. If you make a question and give some details, tag me and I'll take a look. – phsyron Sep 17 '21 at 13:12
-
Its also possible to use import name not as string. Anyone know when one should use over the other? Or there is no difference? I mean I can do `__all__ = ['a']` and `__all__ = [a]`. – Andrius Feb 06 '22 at 16:14
-
it is discouraged to do this: Wildcard imports (from
import *) should be avoided https://www.python.org/dev/peps/pep-0008/ – ArtificiallyIntelligence Feb 17 '22 at 04:10 -
3@ArtificiallyIntelligence From PEP 8: "There is one defensible use case for a wildcard import, which is to republish an internal interface as part of a public API." Besides, the question and answer are regarding the usage of the __all__ special variable, and don't endorse wildcard imports. That is simply __all__'s usage. – Xbox One Jun 28 '22 at 18:13
It's a list of public objects of that module, as interpreted by import *
. It overrides the default of hiding everything that begins with an underscore.

- 89,068
- 17
- 119
- 137
-
190Objects that begin with an underscore, or are not mentioned in `__all__` if `__all__` is present, are not exactly hidden; they can be seen and accessed perfectly normally if you know their names. It is only in the case of an "import *", which is not recommended anyway, that the distinction carries any weight. – Brandon Rhodes Dec 08 '09 at 18:40
-
35@BrandonRhodes: that’s not exactly true either: It’s recommended to only import modules that you know to be designed for `import *` (like e.g. `tk`). A good hint if this is the case is the presence of `__all__` or names starting with underscore in the module’s code. – flying sheep Apr 07 '12 at 22:15
-
22Public and internal interfaces - https://www.python.org/dev/peps/pep-0008/#id50, To better support introspection, modules should explicitly declare the names in their public API using the \_\_all\_\_ attribute. Setting \_\_all\_\_ to an empty list indicates that the module has no public API. – debug Apr 10 '18 at 15:20
-
5I'm not sure that if `tk` were released today (or in 2012, even), the recommended practice would be to use `from tk import *`. I think the practice is accepted due to inertia, not intentional design. – chepner Nov 06 '19 at 15:36
-
9To summarize: If you have `__all__`, `import *` will import everything in the `__all__`, otherwise, it will import everything that does not start with an underscore. – JP Zhang May 07 '21 at 03:16
-
If you only have in your ``__init__.py`` symbols that are imported from a source e.g. ``from .my_source import a, b, c``, adding ``__all__= [a,b,c]`` is redundant : no other symbol of my_source.py will be visible. – Eric H. Aug 24 '21 at 05:31
Explain all in Python?
I keep seeing the variable
__all__
set in different__init__.py
files.What does this do?
What does __all__
do?
It declares the semantically "public" names from a module. If there is a name in __all__
, users are expected to use it, and they can have the expectation that it will not change.
It also will have programmatic effects:
import *
__all__
in a module, e.g. module.py
:
__all__ = ['foo', 'Bar']
means that when you import *
from the module, only those names in the __all__
are imported:
from module import * # imports foo and Bar
Documentation tools
Documentation and code autocompletion tools may (in fact, should) also inspect the __all__
to determine what names to show as available from a module.
__init__.py
makes a directory a Python package
From the docs:
The
__init__.py
files are required to make Python treat the directories as containing packages; this is done to prevent directories with a common name, such as string, from unintentionally hiding valid modules that occur later on the module search path.
In the simplest case,
__init__.py
can just be an empty file, but it can also execute initialization code for the package or set the__all__
variable.
So the __init__.py
can declare the __all__
for a package.
Managing an API:
A package is typically made up of modules that may import one another, but that are necessarily tied together with an __init__.py
file. That file is what makes the directory an actual Python package. For example, say you have the following files in a package:
package
├── __init__.py
├── module_1.py
└── module_2.py
Let's create these files with Python so you can follow along - you could paste the following into a Python 3 shell:
from pathlib import Path
package = Path('package')
package.mkdir()
(package / '__init__.py').write_text("""
from .module_1 import *
from .module_2 import *
""")
package_module_1 = package / 'module_1.py'
package_module_1.write_text("""
__all__ = ['foo']
imp_detail1 = imp_detail2 = imp_detail3 = None
def foo(): pass
""")
package_module_2 = package / 'module_2.py'
package_module_2.write_text("""
__all__ = ['Bar']
imp_detail1 = imp_detail2 = imp_detail3 = None
class Bar: pass
""")
And now you have presented a complete api that someone else can use when they import your package, like so:
import package
package.foo()
package.Bar()
And the package won't have all the other implementation details you used when creating your modules cluttering up the package
namespace.
__all__
in __init__.py
After more work, maybe you've decided that the modules are too big (like many thousands of lines?) and need to be split up. So you do the following:
package
├── __init__.py
├── module_1
│ ├── foo_implementation.py
│ └── __init__.py
└── module_2
├── Bar_implementation.py
└── __init__.py
First make the subpackage directories with the same names as the modules:
subpackage_1 = package / 'module_1'
subpackage_1.mkdir()
subpackage_2 = package / 'module_2'
subpackage_2.mkdir()
Move the implementations:
package_module_1.rename(subpackage_1 / 'foo_implementation.py')
package_module_2.rename(subpackage_2 / 'Bar_implementation.py')
create __init__.py
s for the subpackages that declare the __all__
for each:
(subpackage_1 / '__init__.py').write_text("""
from .foo_implementation import *
__all__ = ['foo']
""")
(subpackage_2 / '__init__.py').write_text("""
from .Bar_implementation import *
__all__ = ['Bar']
""")
And now you still have the api provisioned at the package level:
>>> import package
>>> package.foo()
>>> package.Bar()
<package.module_2.Bar_implementation.Bar object at 0x7f0c2349d210>
And you can easily add things to your API that you can manage at the subpackage level instead of the subpackage's module level. If you want to add a new name to the API, you simply update the __init__.py
, e.g. in module_2:
from .Bar_implementation import *
from .Baz_implementation import *
__all__ = ['Bar', 'Baz']
And if you're not ready to publish Baz
in the top level API, in your top level __init__.py
you could have:
from .module_1 import * # also constrained by __all__'s
from .module_2 import * # in the __init__.py's
__all__ = ['foo', 'Bar'] # further constraining the names advertised
and if your users are aware of the availability of Baz
, they can use it:
import package
package.Baz()
but if they don't know about it, other tools (like pydoc) won't inform them.
You can later change that when Baz
is ready for prime time:
from .module_1 import *
from .module_2 import *
__all__ = ['foo', 'Bar', 'Baz']
Prefixing _
versus __all__
:
By default, Python will export all names that do not start with an _
when imported with import *
. As demonstrated by the shell session here, import *
does not bring in the _us_non_public
name from the us.py
module:
$ cat us.py
USALLCAPS = "all caps"
us_snake_case = "snake_case"
_us_non_public = "shouldn't import"
$ python
Python 3.10.0 (default, Oct 4 2021, 17:55:55) [GCC 10.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from us import *
>>> dir()
['USALLCAPS', '__annotations__', '__builtins__', '__doc__', '__loader__', '__name__', '__package__', '__spec__', 'us_snake_case']
You certainly could rely on this mechanism. Some packages in the Python standard library, in fact, do rely on this, but to do so, they alias their imports, for example, in ctypes/__init__.py
:
import os as _os, sys as _sys
Using the _
convention can be more elegant because it removes the redundancy of naming the names again. But it adds the redundancy for imports (if you have a lot of them) and it is easy to forget to do this consistently - and the last thing you want is to have to indefinitely support something you intended to only be an implementation detail, just because you forgot to prefix an _
when naming a function.
I personally write an __all__
early in my development lifecycle for modules so that others who might use my code know what they should use and not use.
Most packages in the standard library also use __all__
.
When avoiding __all__
makes sense
It makes sense to stick to the _
prefix convention in lieu of __all__
when:
- You're still in early development mode and have no users, and are constantly tweaking your API.
- Maybe you do have users, but you have unittests that cover the API, and you're still actively adding to the API and tweaking in development.
An export
decorator
The downside of using __all__
is that you have to write the names of functions and classes being exported twice - and the information is kept separate from the definitions. We could use a decorator to solve this problem.
I got the idea for such an export decorator from David Beazley's talk on packaging. This implementation seems to work well in CPython's traditional importer. If you have a special import hook or system, I do not guarantee it, but if you adopt it, it is fairly trivial to back out - you'll just need to manually add the names back into the __all__
So in, for example, a utility library, you would define the decorator:
import sys
def export(fn):
mod = sys.modules[fn.__module__]
if hasattr(mod, '__all__'):
mod.__all__.append(fn.__name__)
else:
mod.__all__ = [fn.__name__]
return fn
and then, where you would define an __all__
, you do this:
$ cat > main.py
from lib import export
__all__ = [] # optional - we create a list if __all__ is not there.
@export
def foo(): pass
@export
def bar():
'bar'
def main():
print('main')
if __name__ == '__main__':
main()
And this works fine whether run as main or imported by another function.
$ cat > run.py
import main
main.main()
$ python run.py
main
And API provisioning with import *
will work too:
$ cat > run.py
from main import *
foo()
bar()
main() # expected to error here, not exported
$ python run.py
Traceback (most recent call last):
File "run.py", line 4, in <module>
main() # expected to error here, not exported
NameError: name 'main' is not defined

- 374,368
- 89
- 403
- 331
-
1Cross reference: I mentioned your decorator in [this CW answer](http://stackoverflow.com/a/41895257/1468366) to the question of how to write an `@export` decorator. – MvG Jan 27 '17 at 13:58
-
68This has single handedly been the most helpful answer I have seen in regards to helping a relatively new python developer understand the process of importing modules/packages with `__init__.py` and the use of `__all__` – Brett Reinhard Nov 07 '17 at 04:21
-
This helps me a lot. My problem, tho, is that the submodules I want to import are all generated files with a lot of cruft in their symbols that I'd like to strip out, without having to manually ensure that `__all__` is correct. – Mike C Aug 12 '19 at 16:32
-
@MikeC then maybe you should generate your `__all__` too - but then I would say you have an unstable API... This would be something to have some comprehensive acceptance tests on. – Russia Must Remove Putin Aug 12 '19 at 17:22
-
@AaronHall "they won't have all the other names ... cluttering up the package namespace" But they *will* have the names `module_1` and `module_2`; is it OK to include an explicit `del module_1` in `__init__.py`? Am I wrong to think this is worthwhile? – Mike C Aug 12 '19 at 23:07
-
Does make sense using `__all__` when I keep the `__init__.py` clean and only explicitly include there like: `from .module1 import fn1, Class1`? --- Unfortunately there are linters which do not understand this and complain about unused imports: https://github.com/PyCQA/pyflakes/issues/162 – pabouk - Ukraine stay strong Feb 14 '22 at 08:18
-
This sentence is confusing: "By default, Python will export all names that do not start with an _". Python doesn't treat names that start with one `_` differently from other names. It's just a convention meant for the human reader that names starting with `_` are meant to be private. Try it: `from foobar import *` will import names that start with `_` – Flimm Mar 28 '22 at 08:43
-
1I clarified: "By default, Python will export all names that do not start with an _ when imported with `import *`." and I added a shell session that demonstrates that this, as described now, works this way. – Russia Must Remove Putin Mar 28 '22 at 15:10
-
`export()` above doesn't work with `typing.TypeAlias` as written. I worked around this by changing signature to `def export(fn, name="")` along with `mod.__all__.append(name or fn.__name__)` and `mod.__all__ = [name or fn.__name__]`. You need to call it as a function for type aliases. Example: `export(MyTypeAlias, "MyTypeAlias")`. Yes, both parameters are needed. – Scott P. Jan 11 '23 at 18:15
-
I have also seen this inside package's `__init__.py` after importing `*` from `module1` and `module2`: `__all__ = (module1.__all__ + module2.__all__)`. Could you explain the purpose of this statement? – ruslaniv May 08 '23 at 07:24
-
1@ruslaniv It looks to me that the intent of that statement is so that the package has it's `__all__` defined to exactly match what it imported with the `from module1 import *` and `from module2 import *` while not including any other symbols that exist within the package as part of its import, if someone where to do `from package import *. For example, if the package contained additional testing scripts or a 3rd submodule that should not be directly accessed yet, that would keep the symbols from those files from being imported unless explicitly imported. – nigh_anxiety Aug 31 '23 at 17:22
I'm just adding this to be precise:
All other answers refer to modules. The original question explicitely mentioned __all__
in __init__.py
files, so this is about python packages.
Generally, __all__
only comes into play when the from xxx import *
variant of the import
statement is used. This applies to packages as well as to modules.
The behaviour for modules is explained in the other answers. The exact behaviour for packages is described here in detail.
In short, __all__
on package level does approximately the same thing as for modules, except it deals with modules within the package (in contrast to specifying names within the module). So __all__
specifies all modules that shall be loaded and imported into the current namespace when us use from package import *
.
The big difference is, that when you omit the declaration of __all__
in a package's __init__.py
, the statement from package import *
will not import anything at all (with exceptions explained in the documentation, see link above).
On the other hand, if you omit __all__
in a module, the "starred import" will import all names (not starting with an underscore) defined in the module.

- 28,719
- 15
- 79
- 106
-
32`from package import *` will still import everything defined in `__init__.py`, even if there is no `all`. The important difference is that without `__all__` it will not automatically import any modules defined in package's directory. – Nikratio Jul 20 '14 at 19:37
-
1When __all__ contains [foo, bar] and in test.py file if we use: from package import *, then, do foo and bar get imported in the local namespace of test.py or in the foo and bars own namespace? – variable Oct 12 '19 at 05:26
It also changes what pydoc will show:
module1.py
a = "A"
b = "B"
c = "C"
module2.py
__all__ = ['a', 'b']
a = "A"
b = "B"
c = "C"
$ pydoc module1
Help on module module1: NAME module1 FILE module1.py DATA a = 'A' b = 'B' c = 'C'
$ pydoc module2
Help on module module2: NAME module2 FILE module2.py DATA __all__ = ['a', 'b'] a = 'A' b = 'B'
I declare __all__
in all my modules, as well as underscore internal details, these really help when using things you've never used before in live interpreter sessions.

- 12,464
- 4
- 50
- 55
__all__
customizes *
in from <module> import *
and from <package> import *
.
A module is a .py
file meant to be imported.
A package is a directory with a __init__.py
file. A package usually contains modules.
MODULES
""" cheese.py - an example module """
__all__ = ['swiss', 'cheddar']
swiss = 4.99
cheddar = 3.99
gouda = 10.99
__all__
lets humans know the "public" features of a module.[@AaronHall] Also, pydoc recognizes them.[@Longpoke]
from module import *
See how swiss
and cheddar
are brought into the local namespace, but not gouda
:
>>> from cheese import *
>>> swiss, cheddar
(4.99, 3.99)
>>> gouda
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'gouda' is not defined
Without __all__
, any symbol (that doesn't start with an underscore) would have been available.
Imports without *
are not affected by __all__
import module
>>> import cheese
>>> cheese.swiss, cheese.cheddar, cheese.gouda
(4.99, 3.99, 10.99)
from module import names
>>> from cheese import swiss, cheddar, gouda
>>> swiss, cheddar, gouda
(4.99, 3.99, 10.99)
import module as localname
>>> import cheese as ch
>>> ch.swiss, ch.cheddar, ch.gouda
(4.99, 3.99, 10.99)
PACKAGES
In the __init__.py
file of a package __all__
is a list of strings with the names of public modules or other objects. Those features are available to wildcard imports. As with modules, __all__
customizes the *
when wildcard-importing from the package.[@MartinStettner]
Here's an excerpt from the Python MySQL Connector __init__.py
:
__all__ = [
'MySQLConnection', 'Connect', 'custom_error_exception',
# Some useful constants
'FieldType', 'FieldFlag', 'ClientFlag', 'CharacterSet', 'RefreshOption',
'HAVE_CEXT',
# Error handling
'Error', 'Warning',
...etc...
]
The default case, asterisk with no __all__
for a package, is complicated, because the obvious behavior would be expensive: to use the file system to search for all modules in the package. Instead, in my reading of the docs, only the objects defined in __init__.py
are imported:
If
__all__
is not defined, the statementfrom sound.effects import *
does not import all submodules from the packagesound.effects
into the current namespace; it only ensures that the packagesound.effects
has been imported (possibly running any initialization code in__init__.py
) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by__init__.py
. It also includes any submodules of the package that were explicitly loaded by previous import statements.
And lastly, a venerated tradition for stack overflow answers, professors, and mansplainers everywhere, is the bon mot of reproach for asking a question in the first place:
Wildcard imports ... should be avoided, as they [confuse] readers and many automated tools.
[PEP 8, @ToolmakerSteve]
-
2I really like this answer, but I'm missing the information on what's the default behavior for `from
import *` without `__all__` in `__init__.py` that is **not importing any of the modules**. – radzak Mar 21 '19 at 15:09 -
Thanks @Jatimir, I clarified as best I could without running experiments. I almost wanted to say this case (asterisk without all for a package) behaves the same **as if `__init__.py` were a module**. But I'm not sure that's accurate, or in particular if underscore-prefixed objects are excluded. Also, I more clearly separated the sections on MODULES and PACKAGES. Your thoughts? – Bob Stein Mar 21 '19 at 17:55
Short answer
__all__
affects from <module> import *
statements.
Long answer
Consider this example:
foo
├── bar.py
└── __init__.py
In foo/__init__.py
:
(Implicit) If we don't define
__all__
, thenfrom foo import *
will only import names defined infoo/__init__.py
.(Explicit) If we define
__all__ = []
, thenfrom foo import *
will import nothing.(Explicit) If we define
__all__ = [ <name1>, ... ]
, thenfrom foo import *
will only import those names.
Note that in the implicit case, python won't import names starting with _
. However, you can force importing such names using __all__
.
You can view the Python document here.

- 9,946
- 8
- 65
- 93
__all__
is used to document the public API of a Python module. Although it is optional, __all__
should be used.
Here is the relevant excerpt from the Python language reference:
The public names defined by a module are determined by checking the module’s namespace for a variable named
__all__
; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in__all__
are all considered public and are required to exist. If__all__
is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ('_').__all__
should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).
PEP 8 uses similar wording, although it also makes it clear that imported names are not part of the public API when __all__
is absent:
To better support introspection, modules should explicitly declare the names in their public API using the
__all__
attribute. Setting__all__
to an empty list indicates that the module has no public API.[...]
Imported names should always be considered an implementation detail. Other modules must not rely on indirect access to such imported names unless they are an explicitly documented part of the containing module's API, such as
os.path
or a package's__init__
module that exposes functionality from submodules.
Furthermore, as pointed out in other answers, __all__
is used to enable wildcard importing for packages:
The import statement uses the following convention: if a package’s
__init__.py
code defines a list named__all__
, it is taken to be the list of module names that should be imported whenfrom package import *
is encountered.

- 1
- 1

- 2,271
- 2
- 32
- 24
__all__
affects how from foo import *
works.
Code that is inside a module body (but not in the body of a function or class) may use an asterisk (*
) in a from
statement:
from foo import *
The *
requests that all attributes of module foo
(except those beginning with underscores) be bound as global variables in the importing module. When foo
has an attribute __all__
, the attribute's value is the list of the names that are bound by this type of from
statement.
If foo
is a package and its __init__.py
defines a list named __all__
, it is taken to be the list of submodule names that should be imported when from foo import *
is encountered. If __all__
is not defined, the statement from foo import *
imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by __init__.py
.
Note that __all__
doesn't have to be a list. As per the documentation on the import
statement, if defined, __all__
must be a sequence of strings which are names defined or imported by the module. So you may as well use a tuple to save some memory and CPU cycles. Just don't forget a comma in case the module defines a single public name:
__all__ = ('some_name',)
See also Why is “import *” bad?

- 142,882
- 41
- 325
- 378
This is defined in PEP8 here:
Global Variable Names
(Let's hope that these variables are meant for use inside one module only.) The conventions are about the same as those for functions.
Modules that are designed for use via
from M import *
should use the__all__
mechanism to prevent exporting globals, or use the older convention of prefixing such globals with an underscore (which you might want to do to indicate these globals are "module non-public").
PEP8 provides coding conventions for the Python code comprising the standard library in the main Python distribution. The more you follow this, closer you are to the original intent.