Tutorials

Godot 4 iOS Export: Run and Debug Godot on iPhone From Windows

Q: My Info.plist changes disappeared after re-exporting. What do I do?

Re-exporting regenerates the whole MyGame.xcodeproj and MyGame folder, so manual changes get overwritten. Put the Info.plist keys you want to keep in Additional Plist Content in the export preset, and usage descriptions in the Privacy group, so every export includes them.

Last updated 2026-10-23

A Godot 4 iOS export is an Xcode project, not an .ipa, so it still has to be compiled, signed and installed before it runs on an iPhone. On the same Windows computer, build the exported project with KXBuild, press F5 to install and debug it on your iPhone, then produce a Release .ipa for the App Store. You export from Godot as usual and use the export folder as a normal Xcode project, without changing your Godot project settings.

You need an Apple Developer account, an iPhone with a cable, and KXBuild installed. Godot option names follow the official docs. As of October 2026, the latest stable Godot is 4.7.2.

What does the Godot 4 iOS export workflow look like?

Godot handles the game itself and the export, and KXBuild handles everything after that.

Step	Where	Output
Build scenes and GDScript	Godot editor	Godot project
Download export templates, fill in the iOS export preset	Godot editor	Export preset
Export	Godot editor	`MyGame.xcodeproj` and related files
Doctor, sign, compile, install, debug	VS Code and KXBuild	The game on your iPhone
Release build	VS Code or the command line	`MyGame.ipa`

The examples use the project name MyGame, the Bundle ID com.example.mygame and the export folder D:\g\mygame-ios.

Step 1: Which Godot version do you need?

This tutorial is written for Godot 4.x, and the options and UI in 4.7.x match what’s shown here. Godot 3.x has different iOS export options and isn’t covered.

Find the version under Help > About Godot in the editor. Export templates must match the editor version exactly, so download them again after you upgrade the editor.

If your project uses C#, note that the Godot docs mark C# iOS export as experimental with many limitations. This tutorial assumes a GDScript project.

Step 2: How do you download export templates?

Export templates are prebuilt iOS versions of the Godot engine, copied into the Xcode project on export.

Open Editor > Manage Export Templates in the Godot editor.
Click Download and Install. The default mirror is fine.
When it’s done, the top of the window shows the current version as installed.

If the download fails on a slow network, download the .tpz file for the same version from the Godot download page and click Install from File in the same window.

Step 3: How do you fill in the iOS export preset?

Open Project > Export, click Add… and choose iOS. The right side lists all options for the preset. Fill them in group by group.

Application group

Option	What to enter
App Store Team ID	Your developer account’s 10-character Team ID, shown under Membership details on the developer website. Required
Bundle Identifier	Must match the App ID registered in the developer portal, such as `com.example.mygame`. Letters, numbers, hyphens and periods only. Required
Min iOS Version	The minimum supported system version. Defaults to 14.0
Short Version	The version shown on the store, such as `1.0.0`. Leave empty to use the project version
Version	The build number, which must be higher than the last upload to App Store Connect. Leave empty to use the project version
Export Project Only	Exports only the Xcode project. Recommended on Windows
Code Sign Identity (Debug / Release)	Leave empty. Debug then uses Apple Development and Release uses Apple Distribution
Provisioning Profile UUID / Specifier	Leave empty. The project then uses automatic signing, and KXBuild matches a profile by Bundle ID

If App Store Team ID or Bundle Identifier is empty, the export window shows an error and won’t export. The Team ID is the 10-character code, not the team name. If it’s wrong, the build can’t find a certificate because the team doesn’t match.

Once you fill in a profile UUID, the exported project switches to manual signing and accepts only that one profile, which easily breaks after you add a phone or renew. Keep it empty.

For choosing a minimum version, see How to choose the minimum iOS version for your app.

Icons group

The most important entries are App Store 1024×1024 and Icon 1024×1024. If you leave other sizes empty, Godot generates them from the project icon. The 1024 App Store icon can’t be transparent or have an alpha channel, or the upload fails with ITMS-90717. See ITMS error codes.

For general icon and launch screen requirements, see iOS app icon sizes, launch screen and localization done right. The launch screen is set in the Storyboard group, where you choose image scaling and the background color.

Privacy group

If your game uses any of the capabilities below, enter a usage description here. It’s written into the exported project’s Info.plist.

Option	Info.plist key	When it’s required
Camera Usage Description	NSCameraUsageDescription	You use the camera
Microphone Usage Description	NSMicrophoneUsageDescription	You use the microphone
Photo Library Usage Description	NSPhotoLibraryUsageDescription	You read or write the photo library

If you use one without a description, the game crashes when it calls it and App Review rejects it. See Info.plist usage descriptions. Each option also has localized variants, so you can enter text for each language.

The same group has privacy manifest options, such as reasons for required reason APIs like file timestamps, disk space and system boot time, whether you track users, and what data you collect. Check them according to what your game and third-party plugins actually do. For the rules, see Write an iOS privacy manifest (PrivacyInfo.xcprivacy) and declare required reason APIs.

Other groups

Capabilities. Performance A12 limits installation to iPhone XS, XR and later, and Performance Gaming Tier limits it to iPhone 15 Pro and later. If you aren’t sure, leave them unchecked, because once checked, older devices can’t see the game on the App Store.
Plugins. If the project has iOS plugins in ios/plugins, they’re listed here. Check each one you use. Unchecked plugins aren’t included in the project.
Additional Plist Content (in the Application group). Put extra Info.plist keys here as an XML fragment of <key> plus value. It’s kept on every re-export, which is more reliable than editing the exported file.

Step 4: Why export to an empty folder?

At the bottom of the export window, click Export Project… and choose the location as follows.

Create an empty folder outside the Godot project, such as D:\g\mygame-ios. Don’t put it inside the Godot project folder, or Godot imports the exported files as project resources.
Enter MyGame.ipa as the file name. The file name sets the name of the Xcode project and target, so don’t use spaces.
Keep Export With Debug checked for now. The debug engine gives more complete error information during development.
Click Save.

If Export Project Only isn’t checked, the export ends with a warning that the .ipa can only be built on macOS and the Xcode project is left as is. That’s expected, and the files you need are already in the export folder.

After the export, the folder contains roughly the following.

File	Purpose
`MyGame.xcodeproj`	The Xcode project that KXBuild opens
`MyGame\`	Project files such as Info.plist, entitlements, icons and the launch screen
`MyGame.pck`	Packed scenes, resources and GDScript
`.xcframework` files	The engine libraries from the export template, plus any checked plugin libraries

Keep the path short, like D:\g\mygame-ios. The engine libraries are deeply nested, and a deep location easily hits path length errors on Windows.

Step 5: Open in VS Code and run doctor

In VS Code, open the export folder D:\g\mygame-ios with File > Open Folder…. The KXBuild view lists the MyGame project and a target with the same name.

The first time you open it, run doctor. It checks what compiling needs and fixes anything missing. Use either of the following.

VS Code extension. Run KXBuild: Doctor (fix environment) from the “···” menu in the KXBuild view’s title bar.
Command line. Run the command below in the export folder.

1kxbuild doctor .\MyGame.xcodeproj

Native code in the export folder (plugin Objective-C and Swift) gets code completion and go to definition in VS Code. See Code completion and indexing. Keep editing GDScript and scenes in Godot.

Step 6: Where does the signing certificate go?

During development you need two things, an Apple Development certificate (.p12) and a Development provisioning profile (.mobileprovision) for the Bundle ID com.example.mygame that includes this iPhone’s UDID. If you don’t have them yet, follow Get an iOS certificate, p12 and provisioning profile on Windows.

The keychain folder can be in either of two places.

keychain\ in the export folder, for example D:\g\mygame-ios\keychain\, which applies only to this project. On re-export Godot cleans only the MyGame.xcodeproj and MyGame\ folders, so keychain\ at the root of the export folder isn’t touched.
%USERPROFILE%\kxbuild\keychain\, shared by all projects, so you don’t have to copy it when the export folder changes.

Put the .p12, the .mobileprovision and password.properties in the folder. In password.properties, write one line per certificate in the form file name=password.

1keychain\
2├─ development.p12
3├─ MyGame_Dev.mobileprovision
4└─ password.properties

The build then signs automatically according to the project’s signing settings, with nothing to configure in KXBuild. See Certificates and signing for the detailed rules.

Step 7: Press F5 to run on your iPhone

Connect your iPhone with a cable, unlock it and tap Trust This Computer. Turn on Developer Mode in Settings > Privacy & Security > Developer Mode, and the phone restarts once. For drivers and phone settings, see Device setup.

Check that the Configuration node in the KXBuild view shows Debug, select the iPhone and press F5. KXBuild builds, signs, installs and launches the game, then attaches the debugger. The first time you debug on a given iOS version, KXBuild downloads device symbols for it, several GB, only once.

To reinstall without recompiling, use Run in the KXBuild view’s title bar, which installs the most recent build and launches it. For the differences between the three launch modes, see Run and debug.

How do you debug native code and GDScript?

Each kind of code has its own debugger, and they don’t interfere with each other.

Code	Where to debug	How
Plugin Objective-C, Swift and C++	VS Code	Set breakpoints in the source and press F5. Stepping, variables and the call stack use the standard debug views
GDScript and scenes	Godot editor	Set breakpoints and run scenes in Godot, using Godot’s own debugger
GDScript output on the device	VS Code, Output > KXBuild Console	Print with `print()` in GDScript

While the game runs on the device, Godot engine logs and GDScript print() and push_error() output go to the system log and show up in the KXBuild Console channel of the VS Code Output panel. Build logs are in the KXBuild channel. Open the Output panel with Ctrl+Shift+U and switch channels in the dropdown at the top right.

For problems that only happen on the iPhone, such as touch input, permission prompts or running out of memory, add print() calls in GDScript to narrow them down. On a crash, VS Code stops at the crash location, and the call stack shows whether the error is in the engine, a plugin or a system framework. For more on reading logs, see Read iPhone device logs with Logger and os_log, then filter and export them.

Do you need to re-export after changes?

After changing GDScript, scenes or resources, export again from Godot to the same folder with the same file name, then go back to VS Code and press F5.

On re-export, Godot clears and regenerates the locations below, and any manual changes you made there are lost.

Location	Contains	Overwritten
`MyGame.xcodeproj`	Project file, build settings, signing settings	Yes, fully regenerated
`MyGame\`	Info.plist, entitlements, icons, launch screen	Yes, fully regenerated
`MyGame.pck`	Scenes, resources, scripts	Yes, replaced by the new export
`keychain\`, `.vscode\` and others at the export folder root	Certificates, VS Code settings	No

So put any change you want to keep back into the Godot export preset.

Extra Info.plist keys go in Additional Plist Content.
Usage descriptions go in the Privacy group.
Version and build numbers go in Short Version and Version.
Device capabilities go in Capabilities.

For a quick experiment, you can edit MyGame\MyGame-Info.plist in the Property List Editor or change build settings in the Project Settings Editor, keeping in mind that the next export wipes them.

Also don’t put your own files in the MyGame\ folder. Godot checks it before re-exporting, and if it finds too many files it doesn’t recognize, it reports Unexpected files found and stops. Move those files out, or export to a new empty folder.

How do you build a Release .ipa for the App Store?

Before packaging, export from Godot once more with two differences.

Make sure Version is higher than your last upload, and Short Version is the version you’re releasing.
Uncheck Export With Debug. The exported project carries one copy of the engine library, and with this checked it’s the debug build, so switch to the release build before packaging.

The keychain folder also needs an Apple Distribution certificate and an App Store provisioning profile. With the Release signing identity in the export preset left empty, the project already uses Apple Distribution, so there’s nothing to change.

Then use either of the following.

VS Code extension. Run KXBuild: Build for App Store (.ipa) from the Command Palette or the project’s context menu.
Command line. Run the command below in the export folder.

1kxbuild build .\MyGame.xcodeproj -c Release --export app-store

When the build finishes, MyGame.ipa is in the build folder of the export folder. Upload it to App Store Connect with Transporter on a Mac or Appuploader on Windows. After processing, send it to testers through TestFlight first, then submit it for review. For the full flow, see Release and App Store submission and Publish to the App Store on Windows, from .ipa upload to review.

How do you fix common Godot 4 iOS export errors?

Symptom	Cause	Fix
The export window says no export templates were found	Templates aren’t installed, or they don’t match the editor version	Download the current version’s templates in Editor > Manage Export Templates
App Store Team ID not specified	The Team ID is empty	Enter the 10-character Team ID in the Application group
Invalid Identifier	The Bundle ID contains underscores, spaces or similar characters	Use only letters, numbers, hyphens and periods
The export ends with .ipa can only be built on macOS	Godot doesn’t produce an .ipa on Windows	Expected. Continue with the exported Xcode project. With Export Project Only checked, the message goes away
Unexpected files found in the export destination directory	The export folder has files Godot doesn’t recognize	Move out the files you added, or use a new empty folder
Metal renderer require iOS 14+	Min iOS Version is below 14	The Forward+ and Mobile renderers use Metal on iOS, so set the minimum back to 14.0 or later
Compiling can’t find a plugin’s headers or symbols	The plugin has no iOS version, or it isn’t checked in the Plugins group	Make sure the plugin ships an iOS library, check it in the export preset and export again
A GDExtension doesn’t load on the iPhone	The `.gdextension` file has no iOS library	Add ios entries under `[libraries]` and provide iOS builds of the library
The game crashes when using the camera or microphone	The usage description is missing	Fill it in the Privacy group and export again
Signing can’t find a provisioning profile	The `keychain` folder has no profile for this Bundle ID, or the profile doesn’t include this phone	Add it as described in Certificates and signing, and compare signing errors against 16 common iOS code signing and .ipa install errors

You choose the renderer in the Rendering section of the Godot project settings. On iOS, the Compatibility renderer uses OpenGL ES 3, while Forward+ and Mobile use Metal. If a Godot 4 iOS export shows rendering glitches or a black screen on launch, export once with the other renderer to check whether it’s a rendering issue.

FAQ

Can Godot export an iOS .ipa directly on Windows?

No. On Windows Godot generates only an Xcode project, and the export ends with a message that the .ipa can only be built on macOS. Open that project with KXBuild on Windows and build with the Release configuration to get an .ipa.

My Info.plist changes disappeared after re-exporting. What do I do?

Re-exporting regenerates the whole MyGame.xcodeproj and MyGame folder, so manual changes get overwritten. Put the Info.plist keys you want to keep in Additional Plist Content in the export preset, and usage descriptions in the Privacy group, so every export includes them.

Can I set breakpoints in GDScript from VS Code?

GDScript uses Godot’s own debugger, so set breakpoints in the Godot editor. VS Code debugs the native code in the exported project, and GDScript print() output on the device shows in KXBuild Console.

What values go in Bundle Identifier and Team ID when exporting?

The Team ID is the 10-character code under Membership details on the developer website, not the team name. The Bundle Identifier must exactly match the App ID registered in the developer portal and the one in your provisioning profile, such as com.example.mygame.

Why uncheck Export With Debug for an App Store build?

The exported project carries one copy of the engine library, and with Export With Debug checked it’s the debug build, which is larger and slower. Uncheck it and export again before building a Release .ipa, then build with the Release configuration.