Build history
Understand the build history and the files Unity records for each Player and content directory build, where Unity stores them, and how to access them.
Read time 5 minutesLast updated a month ago
When you make a Player or content directory build, Unity records a build report and several supporting files that describe how the build ran and what it produced. These files are for development, debugging, and analysis only. Unity doesn't require them to run the Player, and you don't ship them with your application. This information is distinct from the content output of a build, which is the data that you distribute.
Unity stores the build report and its supporting files together in a build report directory, and keeps a history of these directories so that you can compare and analyze builds over time. You can access this data through the Build Analysis window in the Unity Editor or from a script, which makes it useful for custom analysis tools and for collecting build information in a continuous integration (CI) pipeline.
Build history structure
Each Player or content directory build creates a build report directory inside the build history. By default, Unity stores the build history in the folder, and creates one directory per build:
Library/BuildHistoryLibrary/ BuildHistory/ 20260504-153912Z-2dd7642e/ # one build report directory per build 2dd7642ecff62df44b2705c4342c6cd7.buildreport BuildReportSummary.json BuildLog.jsonl ... 20260504-153855Z-7aff42f4/ # another build ...
A single build can produce more than one build report directory. For example, if a Player build triggers content builds from a callback, Unity records a separate build report directory for each content build. The content build directories are ordered before the build report directory for the Player build.
BuildPlayerProcessor.PrepareForBuildThe build history is separate from the build output, so you can archive or delete build report directories to free disk space without affecting built content or the ability to run the Player.
Build history compatibility
The build history behaves differently for each build pipeline as follows:
Build pipeline | Behavior |
|---|---|
| Player builds | Unity writes the build report directory and also copies the build report to |
| Content directory builds | Full build history support for builds created with |
| Addressables | When you configure Addressables to build content directories, each Addressables build creates a build report directory like a direct call to |
| AssetBundles | Builds created with |
| External build pipelines | Build systems that run outside the Unity build pipeline, such as your own build tools. Unity doesn't track these builds automatically; an external build system can register its builds with |
Files in the BuildHistory folder
Unity records build history information as several separate files rather than one large file. Each file holds a different kind of data, such as the build report, the build log, profiling traces, and the content layout. This keeps each file focused, lets Unity produce each one independently, and means a tool only needs to open the file it's interested in.
The files Unity writes depend on the build type. For more information about the files in the build history output refer to Build history file reference.
Failed, cancelled, and interrupted build behavior
In addition to successful builds, Unity records build report directories for failed or cancelled builds, which is useful when you investigate a build problem. Unity creates a build history at the start of the build process with a result, then updates it with the final result when the build completes. If the Editor process stops during a build, for example because of a crash, the build report directory remains with its result and might not contain all the files.
BuildResult.PendingPendingBuild history retention
To prevent the build history from growing without limit, Unity applies a retention policy at the start of each build. sets the maximum number of builds to keep. When a new build exceeds the limit, Unity deletes the oldest entries. Set the limit to to disable automatic deletion.
BuildHistory.BuildHistoryLimit0This limit is a per-project setting that Unity stores in . You can also set it in the Build Pipeline Project Settings window ( > Build Pipeline).
UserSettings/BuildPipelineSettings.assetProject Settings
?
Share and capture build history
Build report directories are self-contained and portable. The API and the Build Analysis window can read a build report directory even if a different machine or a different Unity project produced it. If you use several build servers, you can combine their build report directories into a single build history folder to analyze them in one place.
BuildHistoryTo capture the build history from an automated build, copy the entire build report directory, or the entire build history folder, rather than selecting individual files. This captures the complete set of outputs, including any that future Unity versions add.
To reduce the disk space that an archived build report directory uses, compress it. Neither the API nor the Build Analysis window can read a build report directory while it's compressed, so extract it again before you access it.
BuildHistory