# What is "ushell", a CLI tool that ships with Unreal Engine? How to use it on Linux? **URL:** \ **Category:** Platform & Builds\ **Tags:** source, Linux, build, tool, unreal-engine, Automation\ **Created:** [February 25, 2024, 12:56am UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808 "2024-02-25T00:56:00Z")\ **Posts on this page:** 7\ **Page:** 1
**Author:** ![dzemzmcdonalda](https://d1ap1mz92jnks1.cloudfront.net/user_avatar/forums.unrealengine.com/dzemzmcdonalda/32/1214680_2.png) [@dzemzmcdonalda](https://forums.unrealengine.com/u/dzemzmcdonalda)\ **Post date:** [February 25, 2024, 12:56am UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808/1 "2024-02-25T00:56:00Z")
Hiya, Looking through Unreal’s source tree I noticed that there is a small CLI tool called `ushell` located under following directory: [[UnrealEngine]/Engine/Extras/ushell](https://github.com/EpicGames/UnrealEngine/tree/5.3/Engine/Extras/ushell) Based on its [README.txt](https://github.com/EpicGames/UnrealEngine/blob/5.3/Engine/Extras/ushell/README.txt), it looks very similar to [ue4cli](https://github.com/adamrehn/ue4cli) which is a wrapper for platform-dependent build scripts. I use `ue4cli` daily and really like it, however said project is stale for past few years so I was searching for some alternatives and thinking about writing something similar on my own. `ushell` might be what I was looking for, as it still seems to be updated with the latest commit to 5.4 branch being only few days old. * * * However, besides the source code and README, I was unable to find any information about this tool. Googling, searching through Unreal Forum, nothing… like if it never existed at all… I was only able to find [this small note in UnrealBuildTool](https://github.com/EpicGames/UnrealEngine/blob/5.3/Engine/Source/Programs/UnrealBuildTool/Modes/IWYUMode.cs#L25) by `ripgrep`’ing the files. * * * The problem is that I’m unable to use this tool on my current Linux machine. I tried to follow the guide by calling `source [UnrealEngine]/Engine/Extras/ushell/ushell.sh` from my project’s working directory, but I’m getting: ```auto [UnrealEngine]/Engine/Extras/ushell/ushell.sh:36: permission denied: [UnrealEngine]/Engine/Extras/ushell/channels/flow/posix/boot.sh ``` * * * # So what exactly is `ushell`? What it does? How can I use it? Where to seek any information about it? There is literally no information about this tool, so I’ll be thankful for any kind of help. Cheers! ---
**Author:** ![Ari\_Epic](https://d1ap1mz92jnks1.cloudfront.net/user_avatar/forums.unrealengine.com/ari_epic/32/956630_2.png) [@Ari\_Epic](https://forums.unrealengine.com/u/Ari_Epic)\ **Post date:** [April 25, 2024, 12:59pm UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808/2 "2024-04-25T12:59:21Z")
UShell is a command-line interface to basically make it easier to do common things in Unreal via command line that would otherwise usually be a headache to invoke UAT or P4 commands, which are long and require you to remember their parameter names. Many programmers at Epic Games use it for quality of life. We’ve made it available to the public to use but it’s offered “as is”, we don’t offer support for it. UShell has tab completion and wraps many common commands into much shorter and convenient aliases. If you look at that [Readme](https://github.com/EpicGames/UnrealEngine/tree/release/Engine/Extras/ushell) you linked, you’ll see some examples of how to use it. 1. `.build editor` 2. `.build game ps4` 3. `.build program UnrealInsights shipping` 4. `.cook game ps4` 5. `.stage game ps4` 6. `.run editor` 7. .`run game ps4 --trace -- -ExecCmds="Zippy Bungle Rainbow"` 8. `.run program UnrealInsights shipping` 9. `.p4 cherrypick 1234567` 10. ` .sln generate` 11. `.info` You can write `.help` in the tool to see more help text. All the information about that tool currently available is in that Readme file and from UShell’s own help texts (try writing just `.p4` or `.build` to see what the command does). ---
**Author:** ![dzemzmcdonalda](https://d1ap1mz92jnks1.cloudfront.net/user_avatar/forums.unrealengine.com/dzemzmcdonalda/32/1214680_2.png) [@dzemzmcdonalda](https://forums.unrealengine.com/u/dzemzmcdonalda)\ **Post date:** [May 2, 2024, 8:17pm UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808/3 "2024-05-02T20:17:03Z")
Few notes: - Per README: `Ensuring a suitable version of Python is available (and possibly a toolchain to build Pips) is left to the user to take care of.` - which might be a problem on Linux distros that forbid `pip`. For example on Arch-based distros, one must use pacman or pipx instead of pip. - I can confirm, this works just fine on Win11 VM: ![image](https://d3kjluh73b9h9o.cloudfront.net/original/4X/a/b/4/ab4b49b43021c71767931ef16ce91d327185f5c3.png) - However, ushell does NOT fully ship with the binaries from Epic Games Launcher, there are only few `.tps` files that won’t make it work. ![image](https://d3kjluh73b9h9o.cloudfront.net/original/4X/d/5/6/d56817097c17d876ced07d868b547fbec8644ffe.png) ---
**Author:** ![dzemzmcdonalda](https://d1ap1mz92jnks1.cloudfront.net/user_avatar/forums.unrealengine.com/dzemzmcdonalda/32/1214680_2.png) [@dzemzmcdonalda](https://forums.unrealengine.com/u/dzemzmcdonalda)\ **Post date:** [May 3, 2024, 7:01pm UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808/4 "2024-05-03T19:01:01Z")
Alright, I made it work on Linux. Shell scripts had no executable permissions which was super easy to fix and upstream [https://github.com/EpicGames/UnrealEngine/pull/11836](https://github.com/EpicGames/UnrealEngine/pull/11836) Few additional notes: - _ushell_ requires exactly Python `3.11`. I have 3.12 and script was not detecting its executable. I had to download a separate version. On Arch-based distros said version is accessible here: [AUR (en) - python311](https://aur.archlinux.org/packages/python311) - `README.txt` says that `ushell.sh` must be sourced, but executing it also works just fine. This is important, because sourcing would NOT work with non-POSIX-compliant shells. - `[project].uproject` file must be associated with proper UE version, otherwise ushell won’t detect it. This is not a big deal on Windows because of `UnrealVersionSelector.exe`, but on other platforms it may must be done manually. On Linux, engine associations are stored under: `~/.config/Epic/UnrealEngine/Install.ini` - For anyone who will be using this on POSIX, I highly suggest to create an alias for _ushell_ - e.g. for bash, it would be `alias name="/absolute/path/to/ushell.sh"` inside of `~/.bashrc` I’m not sure, if everything works as it should. I’m still testing it on Linux. I’ll keep this post open for a while as it is the only public information about _ushell_ right now. Literally, the only one that shows up when googling. I’ll try to update the post with any good findings. Cheers! ---
**Author:** ![dzemzmcdonalda](https://d1ap1mz92jnks1.cloudfront.net/user_avatar/forums.unrealengine.com/dzemzmcdonalda/32/1214680_2.png) [@dzemzmcdonalda](https://forums.unrealengine.com/u/dzemzmcdonalda)\ **Post date:** [August 21, 2024, 12:41pm UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808/5 "2024-08-21T12:41:35Z")
PR got accepted and merged into main branch as of [a92c5c](https://github.com/EpicGames/UnrealEngine/commit/a92c5ce28e003ec1b01537376542e2a8eadfd4e2), so problem should be solved in next UE release. ---
**Author:** ![rickyviking](https://d3kjluh73b9h9o.cloudfront.net/original/4X/2/8/5/28502927f1d97ba1051b3b47ccfe17233bf41ef0.png) [@rickyviking](https://forums.unrealengine.com/u/rickyviking)\ **Post date:** [September 25, 2024, 12:55pm UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808/6 "2024-09-25T12:55:51Z")
As metioned by @dzemzmcdonalda, Unreal 5.4 prebuilt version as downloaded from Epic Games Launcher does not provide the needed files to run ushell, only a few .tps file. Is this a known issue? Any option to have ushell available with prebuilt binaries? Thank you ---
**Author:** ![David\_Morasz](https://d1ap1mz92jnks1.cloudfront.net/user_avatar/forums.unrealengine.com/david_morasz/32/247970_2.png) [@David\_Morasz](https://forums.unrealengine.com/u/David_Morasz)\ **Post date:** [May 7, 2025, 12:36pm UTC](https://forums.unrealengine.com/t/what-is-ushell-a-cli-tool-that-ships-with-unreal-engine-how-to-use-it-on-linux/1710808/7 "2025-05-07T12:36:11Z")
Unbeknownst to me, I have been developing a more versatile version of this for years [Nuke.Unreal](https://github.com/microdee/Nuke.Unreal) ([and an article I wrote for a previous version](https://mcro.de/c/log/nuke-unreal-1-2)). I need to do more PR on this