Skip to content

Packaging

Start with a Development build so you can run your game outside the editor and check the logs before making a Shipping build.

  1. In Unreal Editor, save your levels and Blueprints. In Edit → Project Settings → Maps & Modes, check Default Maps → Game Default Map.

    Game Default Map under Default Maps in the Maps & Modes project settings

  2. Add the Python packages your game needs to [project].dependencies in pyproject.toml. If you changed dependencies, restart the editor so UnrealPy can sync them before you build.

  3. From your project folder, run the UnrealPy packaging command. See the command line reference for the launcher location.
unrealpy package                         # Development build into Saved/Packaged
unrealpy package --config Shipping       # a Shipping build
unrealpy package --archive-dir D:\Builds\MyGame

unrealpy package runs the Unreal build and stages Python and its runtime dependencies.

The environment

  • The runtime environment is prepared in Intermediate/UnrealPy/RuntimeVenv with uv sync --no-dev and staged from there. Your development .venv is left untouched and is not shipped.
  • It installs exactly what uv.lock records (--locked) and never changes the lock. If the lock no longer matches pyproject.toml, packaging stops: start the editor once or run unrealpy env, then package again.
  • Put everything the game imports at runtime in [project] dependencies. Dev tools do not ship.
  • Runtime dependencies must be regular packages, not editable installs.
  • --group NAME (repeatable) adds a dependency group to the staged environment.
  • A packaged game never initialises project files, installs uv or downloads anything.

Options

Option Effect
--config Development, DebugGame, Test or Shipping.
--archive-dir PATH Where to archive (default Saved/Packaged, relative to the project).
--uat-arg=-flag, or anything after -- Extra BuildCookRun arguments.
UNREALPY_STAGE_EXCLUDE Environment variable: paths under Python/ to leave out, separated by ;.

Startup

Set Startup Module if you need a Python function to run once on game launch. See Run code at game startup.

Test the package

Open Saved/Packaged (or the archive folder you chose) and launch the Development build. Open a level that uses your Python code and exercise the same behavior you checked in Play In Editor. If a script fails only in the package, check its game log for a missing module or type.

For the interactable door, set the saved door level as Game Default Map before building. Start the packaged executable, press E, and verify that the door opens at the angle you set in Details. Press E again to close it. In the Development build, look for Door toggled on screen or in the game log to confirm the Blueprint received the dispatcher.

Run packaging on a build machine

Give the build machine the same engine and plugin builds as the team. Run from the checkout containing the .uproject and pass an archive directory that your CI system can collect:

unrealpy package --config Development --archive-dir Saved/CI/Development

Treat a failing command as a failed build and keep its log with the archive. Use the same door smoke test on the resulting executable before promoting the build.

Once the Development build works, package again with --config Shipping.