Unity Build & Deploy

Retrieval Sources

Key Guidelines

Build Profiles & Scene List

In Unity 6, the window at File > Build Profiles replaced the older "Build Settings" window — the docs explicitly flag this rename (Manual/BuildSettings.html: "The Build Profiles window was previously named Build Settings"). There are two profile types: Platform profiles (one per installed platform, sharing settings like Development Build and the scene list across all platform profiles) and named Build Profiles (independent, savable configurations with their own scene list, stored as asset files so they go through version control). Switching the active platform/profile gates which Player Settings tab is editable — always confirm the active profile before touching Player Settings. A scene not added to the profile's scene list is silently excluded from the build even though it loads fine in the Editor via File > Open Scene.

File > Build Profiles > select Android (or duplicate as a new named profile)
Scene List panel > drag scenes from Project window, verify checkboxes are ticked
Switch Profile > confirms this profile is now EditorUserBuildSettings.activeBuildTarget

Player Settings

Player Settings hold identification (Company Name, Product Name — these drive Application.persistentDataPath and the bundle identifier com.CompanyName.ProductName), the icon set, splash screen, scripting backend, API compatibility level, and per-platform overrides (Android, iOS, WebGL each get their own settings block, documented separately: class-PlayerSettingsAndroid.html, class-PlayerSettingsiOS.html, class-PlayerSettingsWebGL.html). Set Company/Product Name before relying on save paths or before generating store listings, because changing the bundle ID after a store submission is treated as a new, unrelated app by both Google Play and the App Store.

using UnityEditor;

PlayerSettings.companyName = "AcmeStudio";
PlayerSettings.productName = "SpaceRunner";
PlayerSettings.SetApplicationIdentifier(NamedBuildTarget.Android, "com.acmestudio.spacerunner");

IL2CPP vs Mono

IL2CPP (Intermediate Language To C++) is Unity's ahead-of-time backend: it converts IL to C++ and compiles native machine code, required on platforms that forbid JIT (iOS, most consoles, WebGL) and default/required for Android and console store submissions. It yields smaller, faster runtime output at the cost of much longer build times, and — critically — it requires a native toolchain for the target platform and generally cannot cross-compile: building a macOS IL2CPP player requires a macOS Editor host, an iOS IL2CPP player requires macOS + Xcode, etc. The one documented exception is Linux, which supports cross-compiling from other desktop hosts (Manual/linux-il2cpp-crosscompiler.html). Mono JIT-compiles, iterates far faster locally, but is unavailable wherever the OS forbids JIT-compiled code. Use Mono for local dev-loop iteration and IL2CPP for release/store builds.

PlayerSettings.SetScriptingBackend(NamedBuildTarget.Android, ScriptingImplementation.IL2CPP);
PlayerSettings.SetIl2CppCodeGeneration(NamedBuildTarget.Android, Il2CppCodeGeneration.OptimizeSpeed);

Android Build & Signing

Unity can build Android output as an APK (default) or Android App Bundle / AAB — Google Play requires AAB, not APK, for new submissions. Toggle this via File > Build Profiles > Android > Build App Bundle (Google Play), visible only when Export Project is disabled; if exporting to Android Studio instead, enable Export Project then Export for App Bundle. Release builds must be signed with a keystore (Manual/android-keystore.html, managed via the Keystore Manager window or Player Settings > Publishing Settings). The docs state explicitly: if you sign an app with a particular key and upload it to a store, all future versions must be signed with the same key — losing or rotating the keystore breaks the store update path permanently (Google Play App Signing can mitigate this if enrolled at first upload, but the local upload key still must stay consistent). Back the keystore file up outside the project directory; it is not source-control-safe to commit and is not recoverable if lost.

"C:\Program Files\Unity\Hub\Editor\6000.3.XXf1\Editor\Unity.exe" ^
  -batchmode -quit -nographics ^
  -projectPath "C:\path\to\Project" ^
  -buildTarget Android ^
  -executeMethod BuildScripts.BuildAndroidRelease ^
  -logFile C:\Logs\android-build.log

static void BuildAndroidRelease() {
    PlayerSettings.Android.keystoreName = "Assets/release.keystore";
    PlayerSettings.Android.keystorePass = System.Environment.GetEnvironmentVariable("KEYSTORE_PASS");
    PlayerSettings.Android.keyaliasName = "release";
    PlayerSettings.Android.keyaliasPass = System.Environment.GetEnvironmentVariable("KEY_ALIAS_PASS");
    EditorUserBuildSettings.buildAppBundle = true;
    var report = BuildPipeline.BuildPlayer(new BuildPlayerOptions {
        scenes = new[] { "Assets/Scenes/Main.unity" },
        locationPathName = "Builds/Android/spacerunner.aab",
        target = BuildTarget.Android,
        options = BuildOptions.None
    });
    if (report.summary.result != UnityEditor.Build.Reporting.BuildResult.Succeeded)
        EditorApplication.Exit(1);
}

Never hard-code keystore passwords in a committed script — pull them from CI secrets/environment variables, as above.

iOS Build & Provisioning

Unity does not produce a signed, submittable iOS binary directly — it exports an Xcode project, and signing/provisioning happens afterward in Xcode (or via xcodebuild/altool/Transporter in CI) using a matching provisioning profile and signing identity from an Apple Developer account. Building requires a macOS host with a compatible Xcode version installed (Manual/ios-requirements-and-compatibility.html). After export, App Store submissions must also answer the encryption-export-compliance question (ITSAppUsesNonExemptEncryption in Info.plist, Manual/ios-encryption-export-regulations.html) — most games without custom crypto declare non-exempt use as false to skip the export-compliance document requirement per submission.

/Applications/Unity/Hub/Editor/6000.3.XXf1/Unity.app/Contents/MacOS/Unity \
  -batchmode -quit -nographics \
  -projectPath "/path/to/Project" \
  -buildTarget iOS \
  -executeMethod BuildScripts.BuildIOS \
  -logFile ~/Logs/ios-build.log

# then, outside Unity, in CI:
xcodebuild -project Builds/iOS/Unity-iPhone.xcodeproj \
  -scheme Unity-iPhone -configuration Release \
  -archivePath build/App.xcarchive archive
xcodebuild -exportArchive -archivePath build/App.xcarchive \
  -exportPath build/export -exportOptionsPlist ExportOptions.plist

WebGL Build

WebGL always uses IL2CPP (no Mono option — JIT is forbidden in the browser sandbox) and produces a Build folder containing <name>.loader.js, <name>.framework.js, <name>.wasm, and <name>.data (plus a .symbols.json for Release builds with Debug Symbols enabled, and a .mem file only for multithreaded builds). Compression method (Gzip/Brotli/Disabled) and Decompression Fallback settings change the served file extensions (.gz, .br, or .unityweb) and directly require matching web server MIME-type/Content-Encoding configuration (Manual/webgl-server-configuration-code-samples.html) — a WebGL build that "works locally" but fails on a real host is almost always a server config mismatch against the chosen compression method, not a Unity bug.

Unity -batchmode -quit -nographics \
  -projectPath "/path/to/Project" \
  -buildTarget WebGL \
  -executeMethod BuildScripts.BuildWebGL \
  -logFile /var/log/webgl-build.log

static void BuildWebGL() {
    PlayerSettings.WebGL.compressionFormat = WebGLCompressionFormat.Brotli;
    PlayerSettings.WebGL.decompressionFallback = true;
    BuildPipeline.BuildPlayer(new BuildPlayerOptions {
        scenes = EditorBuildSettingsScene.GetActiveSceneList(EditorBuildSettings.scenes),
        locationPathName = "Builds/WebGL",
        target = BuildTarget.WebGL
    });
}

CI / Batch-Mode Builds

Unity 6 documents four command-line build shapes (Manual/build-command-line.html): trigger with -build alone against -buildTarget or -activeBuildProfile (no custom script, equivalent to clicking Build in the Build Profiles window), or combine -executeMethod with either -buildTarget or -activeBuildProfile to run a custom scripted build. Required args are -projectPath <path> and -quit; strongly recommended args are -batchmode, -logFile <path>, and explicitly specifying -buildTarget/-activeBuildProfile — omitting the target makes Unity reuse whatever configuration was last active in the Editor, which is non-deterministic in CI. Add -nographics on headless build agents with no GPU/display. A hard batch-mode limitation: you cannot build multiple targets in one invocation — BuildProfile.SetActiveBuildProfile, EditorUserBuildSettings.SwitchActiveBuildTargetAsync, and BuildPlayerOptions.target all fail to take effect mid-process because a platform switch triggers an assembly reload that cannot happen while a script is running. Run one Unity process per target platform instead.

"C:\Program Files\Unity\Hub\Editor\6000.3.XXf1\Editor\Unity.exe" ^
  -executeMethod BuildScripts.BuildWindows64 ^
  -buildTarget StandaloneWindows64 ^
  -batchmode -quit ^
  -projectPath "C:\path\to\Project" ^
  -logFile C:\Logs\build.log

The -executeMethod target should return a non-zero process exit code on failure (e.g. EditorApplication.Exit(1) after inspecting BuildReport.summary.result) so CI can gate on exit status — don't rely on scraping build.log alone, since Unity can exit 0 even when the scripted logic threw before calling BuildPipeline.BuildPlayer.

Managed Code Stripping

Managed code stripping runs the Unity linker (UnityLinker), which performs static analysis over your project's managed assemblies (project scripts, packages/plugins, .NET Framework assemblies) at build time to remove unreachable classes, methods, and fields. Because it's static analysis, it cannot see code paths that only exist at runtime — anything invoked purely via reflection, Activator.CreateInstance, JSON-driven type lookup, or dependency injection looks "unreachable" and gets stripped unless you tell the linker to preserve it. Configure the stripping level (Minimal / Low / Medium / High — set per platform in Player Settings, Manual/managed-code-stripping-configure.html) and preserve specific code either with the [Preserve] attribute on classes/members or with a link.xml file at the project root (Manual/managed-code-stripping-xml-formatting.html) that whitelists assemblies, types, or members by name.

<!-- link.xml — preserve a type only referenced via reflection -->
<linker>
  <assembly fullname="Assembly-CSharp">
    <type fullname="MyGame.SaveData.PlayerProfile" preserve="all"/>
  </assembly>
</linker>

Common Mistakes

Quick Reference

Advanced Notes

Build automation pipelines. A robust headless pipeline separates three concerns: (1) a static build script implementing IPreprocessBuildWithContext/IPostprocessBuildWithContext (Manual/build-callbacks.html) for environment-specific setup (injecting version numbers, swapping config files, validating required scenes are present) so this logic lives in source control rather than in ad hoc CI YAML; (2) a CLI invocation per target platform that always pins -buildTarget/-activeBuildProfile explicitly and never relies on "whatever the Editor last had active," since CI runners are frequently reused across branches/targets; (3) a post-build verification step that inspects the returned BuildReport (summary.result, summary.totalErrors, summary.totalWarnings) and fails the CI job on a non-Succeeded result via process exit code — treat build.log as a debugging artifact, not the pass/fail signal. For matrix builds (e.g. Windows + Android + WebGL from one commit), fan out to separate Unity processes/agents per target rather than trying to loop targets within a single Editor invocation, since target switching in batch mode does not reliably complete before the next script line runs (the assembly-reload constraint documented in Manual/build-command-line.html). Cache the Library folder between CI runs (Unity's asset database/import cache) to avoid full reimports on every build; a completely clean build should still be exercised periodically via Manual/build-clean-build.html's clean-build option to catch stale-cache bugs.

Per-platform submission requirements. Android: Google Play requires an AAB (not APK) with a targetSdkVersion meeting Play's current minimum (check Manual/android-distribution-google-play.html and Manual/android-setup-target-api.html for the current floor, since Google raises this annually), signed consistently with the original upload key — enrolling in Google Play App Signing at first upload lets Google manage the app signing key while you retain an upload key, but the upload key itself must still remain stable. iOS: App Store Connect requires an archived, signed .ipa built from the Xcode project Unity exports, a valid distribution provisioning profile and signing certificate from an Apple Developer Program membership, and an answer to the ITSAppUsesNonExemptEncryption compliance question (Manual/ios-encryption-export-regulations.html); App Store builds also go through app-thinning/app-slicing (Manual/ios-app-slicing.html) which affects on-demand resource strategy for large asset sets. WebGL: there is no "app store" gate, but hosting requirements are strict — the serving origin must send correct Content-Encoding/MIME types matching the chosen compression method (Manual/webgl-server-configuration-code-samples.html), and browser memory limits mean large WebGL builds need Decompression Fallback or streaming considerations validated before shipping. Across all platforms, run a store-representative build (correct stripping level, correct scripting backend, Development Build disabled) through at least a smoke-test pass before submission — the common failure mode is a build that only ever ran as an Editor Play session or an unstripped Development Build, which behaves differently than the stripped IL2CPP Release artifact a store actually receives.