Xcode Build-System Opt‑Out: When to Use the Legacy Build System

Decision Guide: Opting Out of Xcode’s New Build System

\n

The Problem and the Takeaway

\n

Xcode’s build system has evolved to deliver faster incremental builds and better Swift concurrency support. Yet many projects still rely on build-phase scripts, third‑party plug‑ins, or older runtime behaviors that work reliably only with the legacy system. The decision isn’t merely “new vs old”; it’s about balancing compatibility, build speed, and future‑proofing your workflow.

\n

Takeaway: You can force Xcode to use the legacy build system per‑scheme, but understand the performance and deprecation implications before doing so.

\n

Supported Options: A Compact Comparison

\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Option	Build System	Incremental Build Speed	Plugin / Script Compatibility	Swift Concurrency Checks	Future‑Proofing
New build system (default)	Powered by the modern build system	Faster incremental builds	May require script updates for older tools	Full checks; parallelism enabled	High; actively maintained
Legacy build system	Activated via USE_NEW_BUILD_SYSTEM=NO	Slower incremental builds; more monolithic builds	Broad compatibility with old build phases and plug‑ins	Checks relaxed or omitted; some concurrency features may not apply	Risk of deprecation; may be removed in future Xcode releases

\n

Trade‑Offs in Practice

\n

Choosing the legacy system gives immediate relief for scripts that break under the new build system’s stricter phase ordering and sandboxing. The trade‑off is longer build times, especially for large projects, because the legacy system cannot parallelize independent build tasks as effectively. Additionally, Swift concurrency features such as async/await and structured concurrency may receive weaker static analysis, and some language-level checks can be omitted entirely.

\n

Conversely, staying on the new build system yields the fastest incremental rebuilds and the most accurate Swift diagnostics, but it may force you to rewrite or refactor build scripts, adjust runpath resolutions, or update plug‑in APIs. Projects that have already migrated report fewer build‑time surprises and smoother CI integration.

\n

Concrete Implementation

\n

To opt out of the new build system for a specific scheme:

\n

\n
1. In Xcode, navigate to Product ▸ Scheme ▸ Edit Scheme.
\n
2. Select the Arguments tab.
\n
3. Click the + button under Environment Variables and add:\n
   \n
   • Name: USE_NEW_BUILD_SYSTEM
   \n
   • Value: NO
   \n
   \n
\n
4. Close the dialog and build the scheme.
\n

\n

Alternatively, you can set the variable from the command line:

\n

USE_NEW_BUILD_SYSTEM=NO xcodebuild -scheme "MyScheme" -configuration Release build

\n

The variable can also be persisted as a build setting in the project editor if you want the opt‑out to apply across all builds of that scheme.

\n

Validation and Results

\n

\n
1. After the build, open the build log. Look for the line "Using legacy build system". Its presence confirms the opt‑out is active.
\n
2. To compare incremental build times, run the same build with the variable absent and then with it set, using:\n

   xcodebuild -showBuildTimingSummary -scheme "MyScheme" build

   \n
\n
3. Record the "Total build time" and "Build task duration" sections. A typical legacy‑system build shows a higher cumulative duration and fewer parallel task slots.
\n
4. If the legacy build takes considerably longer for your project without providing a critical compatibility benefit, staying on the new system is usually the better choice.
\n

\n

Limitations: The legacy build system may be removed in a future Xcode release, which could cause build failures for projects that have not updated their scripts. Some Swift language features that rely on the new system’s parallelism may not be fully supported, and you may encounter missing diagnostics or runtime errors.

\n

Practical check: Run xcodebuild -showBuildTimingSummary on a clean build target both with and without USE_NEW_BUILD_SYSTEM=NO. Compare the "Build time" and "Task parallelism" metrics. If the legacy build takes considerably longer for your project without providing a critical compatibility benefit, staying on the new system is usually the better choice.