Unreal Engine 5 Documentation has been moved to the Epic Developer Community

Building for iOS on Windows

How to remotely compile on a Mac from a Windows machine to create an iOS build.

Choose your operating system:

Windows

macOS

Linux

Prerequisite Topics

In order to understand and use the content on this page, make sure you are familiar with the following topics:

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 .

You can find the direct download for iTunes by scrolling down the page

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

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 .

    Users & Groups is located under System Preferences

  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 .

    Use your credentials to unlock the advanced options, then access them with CTRL+Click

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

    Set the dropdown to bin/bash

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 .

    The location of System Preferences/Sharing

  2. Check the box for Remote Login .

    The Remote Login configuration in Sharing

  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.

    The Preferences/Network menu shows your Mac's IP address

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 .

    Locating the project settings in the Edit menu

  2. Navigate to Platforms > iOS > Build .

    The Platforms/iOS section

  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.

    Build options for remote builds, including the server name and 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

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 .

    The config editor button next to the Remote Server Name property

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

    Editing the .ini files with the config editor

  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.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss