Use the BuildHistory class to enumerate and query builds from the Unity Editor. For example, BuildHistory.GetAllBuilds returns the builds from most recent to oldest, and BuildHistory.LatestBuildReportDirectory returns the directory created by the most recent build. To configure the build history, including its location and retention, refer to the BuildHistory scripting reference.
Each build has a unique build session GUID, which is the authoritative identifier for the build. The directory name is a human-readable label that’s convenient for sorting by time, but don’t write code that parses the directory name. To find a build, query the BuildHistory API or read from the BuildReportSummary struct.
External tools can read the build history directly from the file system. For very large builds, it can be more efficient to import the JSON files into another format for querying, such as a SQLite database, rather than parsing them repeatedly.
The Unity Editor also includes a Build Analysis window that presents this data visually. It’s built on top of the BuildHistory API.
The build history also contains a cache folder that holds derived data, such as the data the Build Analysis window computes from the build report directories. Unity can regenerate this data on demand, so you can delete the cache folder to reclaim disk space.
You can add your own files to a build report directory from a build callback, for example to record the source control revision that produced a build. Add files from an IPostprocessBuildWithContext callback, which is the only callback that can safely access the build report directory. Use BuildHistory.TryGetBuildReportDirectory to find the directory during the build. For more information about build callbacks, refer to Use build callbacks.
Don’t use the BuildHistory API to find the current build report directory from IProcessSceneWithReport, IPreprocessShaders, or IPreprocessComputeShaders callbacks. These callbacks can run inside worker processes that don’t have access to the build history.
Unity provides dedicated APIs for the two most important files: BuildHistory.LoadBuildReport returns the build report, and BuildHistory.GetBuildSummary returns the summary. For any other file, including custom files that tools add to the directory, retrieve the file by name with BuildHistory.TryGetFilePath, or get the directory with BuildHistory.TryGetBuildReportDirectory and read its contents with standard file system APIs. The following example finds the most recent Player build, lists the files in its build report directory, and reads the first line of its build log:
using System.IO;
using System.Text;
using UnityEditor;
using UnityEditor.Build;
using UnityEditor.Build.Reporting;
using UnityEngine;
public class BuildHistoryFilesExample
{
// Finds the most recent Player build in the build history and inspects the files in its build
// report directory. Most files have no dedicated API, so you locate the directory and read
// them with ordinary file system APIs.
[MenuItem("Build/Inspect Latest Player Build Report")]
public static void InspectLatestPlayerBuild()
{
// GetAllBuilds returns the build session GUIDs ordered from most recent to oldest.
foreach (var buildSessionGuid in BuildHistory.GetAllBuilds())
{
BuildReportSummary summary = BuildHistory.GetBuildSummary(buildSessionGuid);
if (summary.BuildType != BuildType.Player)
continue;
if (!BuildHistory.TryGetBuildReportDirectory(buildSessionGuid, out string directory) || !Directory.Exists(directory))
continue;
var report = new StringBuilder();
report.AppendLine($"Latest Player build: {summary.PlatformName} started at {summary.BuildStartedAt}");
report.AppendLine($"Build report directory: {directory}");
foreach (string file in Directory.GetFiles(directory))
report.AppendLine($" {Path.GetFileName(file)}");
// Read a specific file, for example the build log, with the standard file system API.
if (BuildHistory.TryGetFilePath(buildSessionGuid, "BuildLog.jsonl", out string buildLogPath))
{
// Read just the first line; ReadLines streams the file so it doesn't load a large log into memory.
foreach (string line in File.ReadLines(buildLogPath))
{
report.AppendLine($"First build log line: {line}");
break;
}
}
Debug.Log(report.ToString());
return;
}
Debug.Log("No Player build found in the build history.");
}
}