Treat init_unreal like __init__

how I use the init_unreal.py files

How It Works

On Editor Startup, Unreal will look for and run all files named init_unreal.py in the Python Path, there are multiple files with that name and only the first one loaded will be available as an actual import:

declaring functions and classes in this file can muddy their file location as they will belong to the __main__ namespace:

Note: For Developers & Technical Staff this can be useful to pre-load Python modules and functions into the __main__ namespace, it can be useful when using the Python CLI in the Output Log window

Further Examining init_unreal

Because Unreal executes every init_unreal.py file it finds in sys.path, there could be any number of competing python modules of the same name

To demonstrate this, here is a code snippet that lists the available init_unreal files and then shows which one is currently importable:

import sys
from pathlib import Path

print("init_unreal modules available:")
for folder_path in sys.path:
    for init_file in Path(folder_path).glob("init_unreal.py"):
        print(f"\t{init_file.resolve()}")

print("Location of imported init_unreal:")
import init_unreal
print(f"\t{init_unreal.__file__}")

This can make it challenging to debug or inspect a specific startup script after Unreal opens.

Example Setup

Because of how init_unreal works, I treat those files files like an __init__.py file:

  • Avoid declaring functions or classes in it directly

  • Import modules as needed, such as a dedicated startup module

  • Call startup functions from imported modules

In my Content/Python folder I usually have a sub-folder for my actual Python code alongside the init_unreal.py file, I mostly do this for organization purposes is all:

My init_unreal.py files usually look something like this:

print("Running the standard init_unreal.py script!")

from devcode import function_library, startup

startup.run()

  • function_library has a BlueprintFunctionLibrary class in it, this import makes the class available to Blueprints

  • the startup.run() function runs my desired startup logic, this helps to reduce confusion if any errors occur and makes it easier to debug / edit if needed

Last updated