UEPyScripts
Overview ✅
UEPyScripts is a collection of Python tools and PowerShell helpers designed to automate common Unreal Engine project tasks (builds, packaging, editor control, CI tasks, etc.).
Table of Contents 📚
- Features
- Requirements
- Installation
- Quick Start
- Usage Examples
- Configuration
- Continuous Integration
- Development & Testing
- Contribution Guide
- Support & Troubleshooting
- License & Credits
Features ✨
- Multiple helper scripts:
- Engine Utilities
- ue-run-buildgraph
- ue-close-editor
- ue-compile-editor
- ue-run-editor
- Continuous Integration helpers:
- ue-ci-cleanup
- ue-ci-run-buildgraph
- Engine Utilities
Requirements ⚙️
- Python 3.12 or newer
- Windows (primary target; other platforms may work)
- Unreal Engine (project-specific; config in
Config/)
Installation 🛠️
-
The easy way is to use UEPyScriptsBootstrap
-
You can download the sources and put them directly in your project
-
You can add as a submodule:
git submodule add git@github.com:TheEmidee/UEPyScripts Scripts/PyScripts -
You can add as a python requirement:
- Create a file named
requirements.txt - Add
UEPyScripts>=1.2.1in this file - Activate a virtual environment :
python -m venv .venvand& ".\.venv\Scripts\Activate.ps1" - Upgrade pip :
python -m pip install --upgrade pip - Install the module :
pip install -r requirements --upgrade
- Create a file named
Usage Examples 🔧
-
Execute a buildgraph target
ue-run-buildgraph.exe --target "Buildgraph Task Name" -set:Clean=True -set:Targets=MyGameClient+MyGameServer -set:TargetConfigurations=Development+Shipping
-
You can directly call
UATorUBT:ue-run-uat.exe turnkey
-
You can generate the visual studio solution:
ue-generate-solution.exe
Configuration 🗂️
Commands read the Project config: every .ini file in your project's Config/PyScripts folder. The files are merged in file-name order, so a later file overrides the same key in an earlier one (for example config.ini, then config.local.ini). Not having the folder is fine: a command only fails when it needs a key that isn't set, and the error lists every missing or malformed key of that section.
- Keys are case-insensitive.
Key =with nothing after it counts as not set. - Lists use
+as the separator. - Relative paths are resolved against the folder that holds the
.uprojectfile. - Sections and keys not listed here are ignored.
[Project]
; BuildGraph XML used by ue-run-buildgraph when --script isn't passed
BuildgraphPath = Build/BuildGraph.xml
; Extra automation script folders passed to UAT as -ScriptDir (missing folders are skipped with a warning)
AutomationScriptsDirectories = Build/Scripts+Plugins/MyPlugin/Build/Scripts
; Properties passed to BuildGraph as -set:Name=Value (split on the first =)
BuildgraphSharedProperties = Clean=False+Targets=MyGameEditor
[Jenkins]
; Shared storage used by ue-ci-run-buildgraph and ue-ci-cleanup (required by both)
BuildgraphSharedStoragePath = \\nas\cache\UE-BuildGraph
[UGS.AWS]
; Used by ue-ugs-push, ue-ugs-pull and ue-ugs-cleanup.
; Each value can be overridden on the command line (--s3-bucket-name, --s3-bucket-region, --s3-access-key, --s3-secret-key)
AWS_BucketName = my-bucket
AWS_Region = eu-west-1
AWS_AccessKey = ...
AWS_SecretKey = ...
Continuous Integration ⚙️
This repository contains several modules that you can call from a continuous integration pipeline. We use Jenkins here but this should work for other tools.
All those modules are very opinionated and work with specific rules. This may lack a bit of flexibility, but this is the result of years of iterations, and it works for us.
Ideally you should be using https://github.com/TheEmidee/JenkinsFileGenerator to generate jenkinsfiles that would use the following modules.
-
uepyscripts.tools.ci.buildgraph: This executes a buildgraph task. This module will call the internaluepyscripts.run.buildgraphbut will inject all arguments that are required to execute a single node, using a shared storage folder to store the artifacts of the task. This basically allows to execute buildgraph tasks in parallel. A typical usage of this module in a jenkins pipeline script would look like:pwsh """ ."Scripts/Python/.venv/Scripts/ue-ci-run-buildgraph.exe" ` --target="${taskName}" ` --build_tag = "${BUILD_TAG}" -set:Clean=True -set:Targets=MyGameClient+MyGameServer -set:TargetConfigurations=Development+Shipping """
You will have to uncomment or add the entry
BuildgraphSharedStoragePathin yourconfig.inifile inConfig/PyScripts:[Jenkins] ; Path to the shared storage directory BuildgraphSharedStoragePath = \\nas\cache\UE-BuildGraph
-
uepyscripts.tools.ci.cleanup: This should be used when your pipeline ends, if you useuepyscripts.tools.ci.buildgraph. This will delete all the files that could have been created as part of the pipeline, in the shared storage folder.stage( 'Cleanup' ) { pwsh """ ."Scripts/Python/.venv/Scripts/ue-ci-cleanup.exe" --build_tag="${BUILD_TAG}" """ }
Development & Testing 🧪
-
Install Astral UV
-
Setup dev environment and install dependencies:
.\setup-venv.ps1
-
In VS Code, you can create a
launch.jsonfile like this one. It's important to use themodulesetting so that relative imports don't raise exceptions.
{
"version": "0.2.0",
"configurations": [
{
"name": "Python Debugger: Current File",
"type": "debugpy",
"request": "launch",
"module": "uepyscripts.tools.ue.compile_editor",
"cwd": "ABSOLUTE_PATH_TO_PROJECT",
"console": "integratedTerminal",
"args": [
"--uproject-path=D:\\PATH_TO_UPROJECT.uproject"
]
}
]
}
- Linting & formatting
- Use
uv run ruff check .anduv run ruff format .Add checks to CI as required. - Use
uv run mypy .
- Use
To create a new release, you must be on the develop branch, and call invoke create_release
Contribution Guide 🤝
We welcome contributions — please follow these steps:
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-change - Add entries in the .changelog folder for towncrier. You can read the README file for more information.
- Run lint locally
- Update documentation
- Submit a pull request describing the change
Support & Troubleshooting ❓
- Check
Config/anduepyscripts/internal/config.pyfor project-specific settings. - If
buildgraphfails, ensureConfig/Projecthas a validBuildgraphPathand the UAT tool is accessible. - When reporting issues, include:
- Python version
- Unreal Engine version
- Exact command and full logs
License & Credits 📝
License: MIT — see the LICENSE file.
Maintainers: Michael Delva and contributors (see AUTHORS or repository metadata).
Changelog: See CHANGELOG.md
Made with ❤️ for Unreal Engine developers — contributions and feedback are welcome! If this helped you, consider starring the repository. ⭐
Metadata
Release files for UEPyScripts 1.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| uepyscripts-1.6.0.tar.gz | 47.9 kB | With provenance | Details for uepyscripts-1.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uepyscripts-1.6.0-py3-none-any.whl | Python 3 | none | any | Details for uepyscripts-1.6.0-py3-none-any.whl |
Total release size: 94.8 kB
Release files / uepyscripts-1.6.0.tar.gz
| Download URL | uepyscripts-1.6.0.tar.gz |
|---|---|
| Size | 47.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1e0aa2ccd87f6afaa797b71e8e1387e65ed8f63e7fcfdcdd04afcda1cc95eb20
|
|
BLAKE2b-256 checksum How to use checksums |
44eefeb9b3838ee81658ad7f9b93784834333346f1f10399a6a23a4b5be699a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / uepyscripts-1.6.0-py3-none-any.whl
| Download URL | uepyscripts-1.6.0-py3-none-any.whl |
|---|---|
| Size | 47.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f2fdbc5233e9ae0f5afb56391762359a8d43b14933bea0b916626f63f34138c9
|
|
BLAKE2b-256 checksum How to use checksums |
2577517361a481db47e1c85af12a13ff86a07d13bcae3f4107d80176aad96abc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for UEPyScripts 1.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for uepyscripts-1.6.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.