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.
Each Player or content directory build creates a build report directory inside the build history. By default, Unity stores the build history in the Library/BuildHistory folder, and creates one directory per build:
Library/
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 BuildPlayerProcessor.PrepareForBuild 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.
The 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.
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 Library/LastBuild.buildreport for backward compatibility. |
| Content directory builds | Full build history support for builds created with BuildPipeline.BuildContentDirectory. |
| Addressables | When you configure Addressables to build content directories, each Addressables build creates a build report directory like a direct call to BuildPipeline.BuildContentDirectory. Whether Addressables builds content directories or AssetBundles, it also writes its own build layout file to its location in the Library folder. This is the main build report for Addressables AssetBundle builds. For more information, refer to the Addressables build layout report. |
| AssetBundles | Builds created with BuildPipeline.BuildAssetBundles aren’t tracked in the build history. They write a build report only to the Library/LastBuild.buildreport path. For information about AssetBundle build output, refer to AssetBundle file format reference. |
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.
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 BuildResult.Pending 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 Pending result and might not contain all the files.
To prevent the build history from growing without limit, Unity applies a retention policy at the start of each build. BuildHistory.BuildHistoryLimit sets the maximum number of builds to keep. When a new build exceeds the limit, Unity deletes the oldest entries. Set the limit to 0 to disable automatic deletion.
This limit is a per-project setting that Unity stores in UserSettings/BuildPipelineSettings.asset. You can also set it in the Build Pipeline Project Settings window (Project Settings > Build Pipeline).
Build report directories are self-contained and portable. The BuildHistory 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.
To 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 BuildHistory API nor the Build Analysis window can read a build report directory while it’s compressed, so extract it again before you access it.