For faster iteration during development, Unity uses an incremental build pipeline that only rebuilds parts of the application if they have changed since the previous build, including build steps such as content building, code compilation, data compressionA method of storing data that reduces the amount of storage space it requires. See Texture Compression, Animation Compression, Audio Compression, Build Compression.
See in Glossary, and signing.
The incremental build pipeline works for both the Mono and IL2CPPA Unity-developed scripting back-end which you can use as an alternative to Mono when building projects for some platforms. More info
See in Glossary scripting backendA framework that powers scripting in Unity. Unity supports three different scripting backends depending on target platform: Mono, .NET and IL2CPP. Universal Windows Platform, however, supports only two: .NET and IL2CPP. More info
See in Glossary, although the output file structure changes depending on which scripting backend your project uses.
By default, Unity uses the incremental build pipeline for both release and development buildsA development build includes debug symbols and enables the Profiler. More info
See in Glossary. See the Creating clean builds section below for details on how to make clean build instead.
Note: The incremental build pipeline does not apply when building AssetBundles. AssetBundles have separate mechanisms for caching and reusing the results from previous builds.
Unity supports the incremental build pipeline for the following platforms:
A “clean build” or “non-incremental build” involves completely rebuilding all content and code without relying on cached results from previous builds. Clean builds are especially useful when preparing release builds or troubleshooting issues caused by corrupted or outdated build caches.
In some scenarios, it can be useful or necessary to create builds that don’t use the incremental build pipeline. For example, you should run a clean build when preparing an official build that will be released.
To create a clean, non-incremental, build:
A clean build can be created from a build script by passing BuildOptions.CleanBuildCache in the call to BuildPipeline.BuildPlayer.
In general, if expected changes are not present after an incremental build and you think there is a problem with the incremental build pipeline, create a clean build.
The content step of the build is when Unity serializes scenesA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary and assets for the target platform. The Incremental Build Pipeline will reuse the entire content output from the previous build if it determines that none of the content has changed since the last successful build. This is always an “all or nothing” decision. This calculation can sometimes be flawed, for example it might reuse content even after you have changed a global settings that influence the output of the build. In this case you should create a clean build.
Some build callbacks happen during the content step of a player build:
When the content is reused from a previous build Unity will not re-trigger those callbacks. They are not invoked because it is presumed that the callbacks were already run on the previous build, so any content change caused by the callback would already be cached in the output from the previous build.
When you change the implementation of a callback, and want to make sure that it is run again, then run a clean build or change the content of one of the scenes or assets that is part of the build.
Other build callbacks that are invoked before or after the content stage of the build may be re-triggered again during an incremental build. In this case the callback implementation should take care that it may be running in the context of a build that already had the callback invoked on it. For example, if the callback adds new entries to an Android App Manifest then it should be careful to work properly when the file already has those entries in it, to avoid creating an invalid file.
A Scripts-only Build is a build that intentionally reuses the content from the previous build, rather than rebuilding it.
When testing script changes it can be useful to force a Scripts-only Build to avoid the time taken to rebuild the content. This can be useful if you know that there are data changes, but want to quickly test a code change, without applying the pending data changes for this purpose.
This type of build can be created by selecting Force skip data build in the Build menu in the Build Profiles window. Custom build scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary can pass the BuildOptions.BuildScriptsOnly flag when calling BuildPipeline.BuildPlayer.
The incremental build pipeline automates the Scripts Only Build feature, so on platforms that support it, the content from the previous build will automatically be reused, so long as the content hasn’t changed. In that case it is not necessary to explicitly invoke a scripts-only build.
Note: The “Force skip data build” option will not work if there have been any changes in the serialization layout of the scripts in the project. For example when you add a new field to a MonoBehaviour then you must perform a regular or clean player build to serialize the assets to match the new class definition.
During normal usage it is not necessary to understand where Unity stores the caches and meta-data files related to the Player Build. However in some cases it can be helpful to understand a bit more detail about the cache locations, for example when investigating issues with low disk space or build problems.
Most cached build content is stored in the Project’s Library directory, in particular the Library/Bee directory. The content from the build is staged and cached in a platform-specific subdirectory of Library/PlayerDataCache.
If the OnPostBuildPlayerScriptDLLs callback has been implemented in your project then the Temp/StagingArea/Data/Managed location is also used during the build to store assemblies.
The content reuse aspect of the incremental build pipeline relies on the files ScriptsOnlyCache.yaml and DataBuildDirtyInfo.json inside the Library/PlayerDataCache directory. These record information about the most recent build of the content, and are required when deciding if that content can be reused. If either of those files are missing Unity will perform a clean build.
The Library directory also stores the Shader Cache and the AssetDatabase, both of which cache data and aid in speeding up subsequent Player builds.
The incremental build pipeline also has a machine-level cache that reuses some specific parts of builds (such as non-embedded packages and libIL2CPP artifacts) across different projects. Other parts of the build, such as content building, are project specific and will not see performance improvements from this cache. The location of this cache is set using the BEE_CACHE_DIRECTORY environment variable, and defaults to a different location depending on your operating system:
BEE_CACHE_DIRECTORY defaults to %USERPROFILE%\AppData\Local\Unity\Caches\bee
BEE_CACHE_DIRECTORY defaults to $HOME/Library/Unity/cache/bee
BEE_CACHE_DIRECTORY defaults to $XDG_CONFIG_HOME/.cache/unity3d/bee (if $XDG_CONFIG_HOME is set) or $HOME/.cache/unity3d/bee
Note: Modifying or deleting these files manually (outside of Unity) can lead to unexpected issues during subsequent builds. These locations and filenames are subject to change between versions of Unity. If you experience build problems related to caching, consider performing a clean build.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.