Building for iOS on Windows

Creating a signed build for iOS requires a Mac and an Apple Developer account. However, for teams that primarily use Windows machines, Unreal Engine 4 (UE4) can establish an SSH connection between a Windows PC and a Mac to create iOS builds remotely. This requires you to allow incoming SSH connections on your Mac, and then you need to set up the SSH key and credentials to access the Mac on your Windows machine. This guide will walk you through this process.

Blueprint-Only iOS Projects on Windows

If you are creating a Blueprint-only iOS project, you do not need to use the full remote-build process detailed in the sections below. Instead, you can use your Windows machine to create your iOS build directly, provided that you have set up your iOS developer certificate and provision profile in the editor. However, if you add C++ code to your project in the future, you will need to follow the steps on this page.

For information on how to sign your build, refer to our guide on iOS Provisioning.

1. Required Setup

To use iOS remote builds, you need at least one Mac capable of building your iOS project, as well as at least one Windows PC. Both machines must have an internet or local area network connection, and both must have the same UE4 project.

Your Windows machine must have iTunes installed to ensure you have the necessary binaries for iOS projects. We recommend that you download and install iTunes from Apple’s web site rather than from the Windows Store, as the Windows version includes extra binaries that sometimes interfere with the remote-build process. To obtain iTunes directly from Apple, scroll down to the section labeled “Looking for other versions?” and click Windows.

Your Mac must have your iOS Developer Certificates installed to the System Keychain, and you must set up your Provisioning Profile for your project, per the iOS Provisioning setup.

Once you have set up your Mac to create builds for your project, you should run a build directly on that machine at least once to ensure that it works before proceeding to the next section.

Setting Bash as the Default Shell Scripting Language on Your Mac (4.26 and Earlier)

As of January 2021, Apple has changed the default shell scripting language from to zsh, which sometimes creates errors launching Unreal Engine builds on iOS. If this happens, the output logs will contain the zsh and rsync errors similar to the following:

	LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Program_Files/Epic_Games/UE_4.26/Engine/Intermediate/IOS/*.plist
	LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Program_Files/Epic_Games/UE_4.26/Engine/Intermediate/TVOS/*.plist
	LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Users/[UserName]/Documents/Unreal_Projects/[ProjectName]/Intermediate/IOS/*.plist
	LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Users/[UserName]/Documents/Unreal_Projects/[ProjectName]/Intermediate/TVOS/*.plist
	LogPlayLevel: [Remote] Executing build
	LogPlayLevel: zsh:1: no matches found: -ini:Game:[/Script/UnrealEd.ProjectPackagingSettings]:BlueprintNativizationMethod=Disabled
	LogPlayLevel: [Remote] Downloading C:\Users[UserName]\AppData\Roaming\Unreal Engine\AutomationTool\Logs\C+Program+Files+Epic+Games+UE_4.26[ProjectName]-IOS-Development_Remote.txt
	LogPlayLevel: rsync: link_stat "/Users/[UserName]/UE4/Builds/[DesktopName]/C/Users/[UserName]/AppData/Roaming/Unreal_Engine/AutomationTool/Logs/C+Program+Files+Epic+Games+UE_4.26/[ProjectName]-IOS-Development_Remote.txt" failed: No such file or directory (2)
	LogPlayLevel: Error: rsync error: some files/attrs were not transferred (see previous errors) (code 23) at /home/lapo/packaging/rsync-3.0.4-1/src/rsync-3.0.4/main.c(1506) [receiver=3.0.4]
	LogPlayLevel: Error: ERROR: Unable to download 'C:\Users[UserName]\AppData\Roaming\Unreal Engine\AutomationTool\Logs\C+Program+Files+Epic+Games+UE_4.26[ProjectName]-IOS-Development_Remote.txt' from the remote Mac (exit code 23).
	LogPlayLevel: Took 21.2652808s to run UnrealBuildTool.exe, ExitCode=5
	LogPlayLevel: UnrealBuildTool failed. See log for more details. (C:\Users[UserName]\AppData\Roaming\Unreal Engine\AutomationTool\Logs\C+Program+Files+Epic+Games+UE_4.26[ProjectName]-IOS-Development.txt)
	LogPlayLevel: AutomationTool exiting with ExitCode=5 (5)
	LogPlayLevel: Completed Launch On Stage: Build Task, Time: 20.779392
	LogPlayLevel: BUILD FAILED
	PackagingResults: Error: Launch failed! Unknown Error
Copy full snippet

LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Program_Files/Epic_Games/UE_4.26/Engine/Intermediate/IOS/*.plist LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Program_Files/Epic_Games/UE_4.26/Engine/Intermediate/TVOS/*.plist LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Users/[UserName]/Documents/Unreal_Projects/[ProjectName]/Intermediate/IOS/*.plist LogPlayLevel: zsh:1: no matches found: /Users/[UserName]/UE4/Builds/[DesktopName]/C/Users/[UserName]/Documents/Unreal_Projects/[ProjectName]/Intermediate/TVOS/*.plist LogPlayLevel: [Remote] Executing build LogPlayLevel: zsh:1: no matches found: -ini:Game:[/Script/UnrealEd.ProjectPackagingSettings]:BlueprintNativizationMethod=Disabled LogPlayLevel: [Remote] Downloading C:\Users[UserName]\AppData\Roaming\Unreal Engine\AutomationTool\Logs\C+Program+Files+Epic+Games+UE_4.26[ProjectName]-IOS-Development_Remote.txt LogPlayLevel: rsync: link_stat "/Users/[UserName]/UE4/Builds/[DesktopName]/C/Users/[UserName]/AppData/Roaming/Unreal_Engine/AutomationTool/Logs/C+Program+Files+Epic+Games+UE_4.26/[ProjectName]-IOS-Development_Remote.txt" failed: No such file or directory (2) LogPlayLevel: Error: rsync error: some files/attrs were not transferred (see previous errors) (code 23) at /home/lapo/packaging/rsync-3.0.4-1/src/rsync-3.0.4/main.c(1506) [receiver=3.0.4] LogPlayLevel: Error: ERROR: Unable to download 'C:\Users[UserName]\AppData\Roaming\Unreal Engine\AutomationTool\Logs\C+Program+Files+Epic+Games+UE_4.26[ProjectName]-IOS-Development_Remote.txt' from the remote Mac (exit code 23). LogPlayLevel: Took 21.2652808s to run UnrealBuildTool.exe, ExitCode=5 LogPlayLevel: UnrealBuildTool failed. See log for more details. (C:\Users[UserName]\AppData\Roaming\Unreal Engine\AutomationTool\Logs\C+Program+Files+Epic+Games+UE_4.26[ProjectName]-IOS-Development.txt) LogPlayLevel: AutomationTool exiting with ExitCode=5 (5) LogPlayLevel: Completed Launch On Stage: Build Task, Time: 20.779392 LogPlayLevel: BUILD FAILED PackagingResults: Error: Launch failed! Unknown Error

If you experience this issue, follow these steps to set bash as your default scripting language instead:

1. Open the Apple Menu, then click System Preferences.

2. Open Users & Groups.

3. Click the lock icon, then enter your account name and password.

4. Control-click your user name in the list of users, then choose Advanced Options.

5. Click the Login shell dropdown menu, then set your shell to bin/bash instead of bin/zsh.

If you package and launch your application again with these settings, it should successfully launch.

These steps apply to Unreal Engine 4.26.0 and earlier. Future releases will support zsh.

2. Enabling Remote Login On Your Mac

Once you have set up your project, you will need to configure your Mac to allow SSH connections.

1. Open your Mac’s System Preferences, then navigate to Sharing.

2. Check the box for Remote Login.

3. Open System Preferences > Network.

4. Note the computer’s IP Address. You will need this for setting up the remote connection on your Windows PC.

Once you have completed these steps, your Mac will be able to accept an incoming SSH connection from your PC.

3. Windows Configuration and Generating Your SSH Key

Complete the following steps on your Windows machine to configure it for remote iOS builds.

1. Open your project in Unreal Editor, then open Project Settings.

   

2. Navigate to Platforms > iOS > Build.

   

3. In the Remote Server Name field, enter either the name of the Mac you are using to build the project, or its IP address.

4. In the Remote User Name field, enter the username that you would normally use to log in to the Mac.

5. Click Generate SSH Key. This will open a Command Prompt window with a series of prompts that will generate the SSH key.

6. If you receive a message that your host could not be authenticated, enter “yes” in the prompt to continue.

7. Enter the password that belongs to the user you specified in Remote User Name in the previous section.

8. The prompt will ask you for a passphrase. If you choose not to enter a passphrase, you can use the remote connection without requiring any user interaction.

9. When prompted, enter the password and username for the Mac again to complete the process.

Now that you have generated an SSH key, you will be able to start a remote connection on your Windows machine to your Mac for creating iOS builds.

Workaround For Unprotected Private Key

You might see an error that reads as follows:

	ERROR: Unable to determine home directory for remote user. SSH output:...WARNING: UNPROTECTED PRIVATE KEY FILE!...0660
Copy full snippet

ERROR: Unable to determine home directory for remote user. SSH output:...WARNING: UNPROTECTED PRIVATE KEY FILE!...0660

If you do not see this error, you can proceed with the next step (Optional Team Setup). If you do see this error, use the following steps to resolve it:

1. Navigate to your RemoteToolChainPrivate.key.

2. Right-click the file and select Properties.

3. Click the Security tab.

4. Click Edit.

5. Remove all group or user names.

6. Click Add.

7. Click Object Types. Make sure all boxes are checked, then click OK.

8. In the text box, type Users, then press Enter.

9. Make sure that permissions for Users are set to Read and Read & Execute.

This will change the file's primary group so that it is not the same as your username, which is what confuses SSH when it checks group permissions. The process should then work as normal.

SubInACL could previously be used for this purpose, but is no longer available from Microsoft.

4. Optional Team Setup

To share this data for other projects in the future, specify the Remote Server Name and Remote User Name in one of the *Engine.ini files on your computer.

1. Select the button next to the Remote Server Name property to open the Configuration Editor.

   

2. Set the properties for each individual .ini file for which you want to share the SSH data.

   

3. Repeat these steps for Remote User Name.

By sharing these .ini files, you can keep the SSH information available for multiple projects or users. The SSH keys themselves are stored in the Engine/Build/SSHKeys folder. You can check this directory into your source control system to share them with your team.

5. Final Result

After completing the above steps, you can initiate a remote build by clicking File > Package Project > iOS in the Unreal Editor on your Windows machine. A SSH connection and send the command to your Mac to begin making a build.