The ‘__init__.py’ File: What Is It? How to Use It? (Complete Guide)

By

__init__.py is a special Python file that is used to indicate that the directory it is in should be treated as a Python package.

Typically, __init__.py is empty, but it can be used to configure the package or set the __all__ variable, which controls what symbols are imported when someone uses from package import *.

Can __init__.py Be Empty?

It is not required to have any content in order for the directory it is in to be treated as a package. It is only used to initialize the package when it is imported, and the contents of the file are executed as part of the import process.

If you don’t need to perform any initialization for your package, then you can leave __init__.py empty.

Do All Python Packages Require __init__.py File?

All Python packages need an __init__.py file before Python 3.3. Python versions of 3.3 or above no longer require the __init__.py file to define a package.

This file is used to indicate that the directory it is in should be treated as a package, and it is required for the package to be importable. Without an __init__.py file, the directory it is in cannot be treated as a package, and any attempt to import the package will fail.

What Does __init__.py Do?

There are several things you can do with an __init__.py file in Python. Here are a few examples:

  • You can use __init__.py to configure the package when it is imported. For example, you can set variables or perform other initialization tasks that are needed for your package to work correctly.
  • You can use __init__.py to define which symbols should be imported when someone uses from package import *. This is done by setting the __all__ variable, which is a list of strings containing the names of the symbols that should be imported.
  • You can use __init__.py to define submodules or sub-packages within your package. This is done by creating subdirectories within your package and placing __init__.py files in those directories as well. This allows you to organize your package into logical units and makes it easier to use and maintain.
  • You can use __init__.py to define the package’s API, which is the set of functions, classes, and other symbols that are intended for public use. This can help users of your package understand what is available for them to use and how to use it.
  • You can use __init__.py to define custom import hooks or other custom behavior for your package. This can be useful for advanced use cases, such as implementing support for alternative module syntax or customizing the way your package is imported.

The __init__.py Is Not Required in Python 3.3+

In Python 3.3 and later versions, the __init__.py file is no longer required for defining a package. This is because the importlib module, which is the core of the import system, has been updated to automatically detect packages without the need for an __init__.py file. This means that you can create a package simply by creating a directory and placing your module files in it, without needing to create an __init__.py file.

Create Package-Level Variables

You can use the __init__.py file to define variables at the package level.

The __init__.py file is executed when a package is imported, so any variables that are defined in this file will be available to all the modules in the package.

For example, you could define a variable named FOO in the __init__.py file in your package called my_pagage:

FOO = "Hello world"

Then, any module in the package can access the value of FOO using the dot notation, like this:

import my_package

print(my_package.FOO)  # Outputs "Hello world"

Notice that the __init__.py file is executed only when the package is imported, so if you change the value of a variable defined in this file, you will need to re-import the package for the changes to take effect.

Summary

Today you learned what is the __init__.py file in Python.

The __init__.py file is used to indicate that the directory it is in should be treated as a Python package. This file is typically empty, but it can be used to perform initialization tasks for the package, such as setting variables or defining submodules.

The __init__.py file is required for the package to be importable, and it is used by the import system to find and load the package when it is imported.

Thanks for reading. Happy coding!