Memory Profiler module

There are two ways of analyzing memory usage in your application in Unity:

• Memory Profiler module: This built-in Profiler module gives you basic information on where your application uses memory.
• Memory Profiler package: This is a separate package that you can add to your Project. It adds an additional Memory Profiler window to the Unity Editor, which you can then use to analyze memory usage in your application in even more detail. You can store and compare snapshots to find memory leaks more easily, or see the memory layout to find memory fragmentation issues.

This page covers information on the built-in Memory Profiler module. For more information on the Memory profiler package, see the Memory Profiler documentation.

The Memory Profiler module visualizes counters that represent the total allocated memory in your application. You can use the memory module to see information like the number of loaded objects, and the memory that they take in total per category. You can also see the number of GC allocations per Profiler frame.

When you profile your application in the Editor, the information in the Memory module indicates the memory usage in the Editor. These numbers are generally larger than when running on the release platform, because running the Unity Editor uses specific objects that take up memory, and the Editor window itself uses extra memory. Additionally, the Profiler displays memory that it uses, because Unity cannot cleanly separate it from the memory that the Play mode Player uses. For more precise numbers and memory usage for your application, connect the Profiler to the running player via the Attach to Player menu. This allows you to see the actual usage on the target device.

Chart categories

The Memory module is divided into six charts that display detailed information on where your application spends memory. You can change the order of the categories in the chart; to do this, drag and drop them in the chart’s legend. You can also click a category’s colored legend to toggle its display.

Module details pane

There are two views available in the module details pane, located at the bottom of the Profiler window: Simple and Detailed. To change the view, select it from the dropdown in the top left of the module details pane.

Simple view

The Simple view displays an overview of how Unity uses memory in real-time on a per-frame basis.

Unity reserves memory pools for allocations to avoid asking the operating system for memory too often. The Profiler displays how much memory is reserved, and how much Unity is using.

This information is also available via the ProfilerRecorder API and in the Profiler Module Editor so you can add them to a custom Profiler module.

Availability in Players

You can use the ProfilerRecorder API to access the Memory Profiler module’s counters in Players. The following example contains a simple script that collects “Total Reserved Memory”, “GC Reserved Memory” and “System Used Memory” metrics, and displays those as a GUI.TextArea. The Memory Profiler module information belongs to the ProfilerCategory.Memory Profiler category.

using System.Text;
using Unity.Profiling;
using UnityEngine;

public class MemoryStatsScript : MonoBehaviour
{
    string statsText;
    ProfilerRecorder totalReservedMemoryRecorder;
    ProfilerRecorder gcReservedMemoryRecorder;
    ProfilerRecorder systemUsedMemoryRecorder;

    void OnEnable()
    {
        totalReservedMemoryRecorder = ProfilerRecorder.StartNew(ProfilerCategory.Memory, "Total Reserved Memory");
        gcReservedMemoryRecorder = ProfilerRecorder.StartNew(ProfilerCategory.Memory, "GC Reserved Memory");
        systemUsedMemoryRecorder = ProfilerRecorder.StartNew(ProfilerCategory.Memory, "System Used Memory");
    }

    void OnDisable()
    {
        totalReservedMemoryRecorder.Dispose();
        gcReservedMemoryRecorder.Dispose();
        systemUsedMemoryRecorder.Dispose();
    }

    void Update()
    {
        var sb = new StringBuilder(500);
        if (totalReservedMemoryRecorder.Valid)
            sb.AppendLine($"Total Reserved Memory: {totalReservedMemoryRecorder.LastValue}");
        if (gcReservedMemoryRecorder.Valid)
            sb.AppendLine($"GC Reserved Memory: {gcReservedMemoryRecorder.LastValue}");
        if (systemUsedMemoryRecorder.Valid)
            sb.AppendLine($"System Used Memory: {systemUsedMemoryRecorder.LastValue}");
        statsText = sb.ToString();
    }

    void OnGUI()
    {
        GUI.TextArea(new Rect(10, 30, 250, 50), statsText);
    }
}

The following screenshot shows the result of adding the script to the Tanks! tutorial project.

This information is available in Release Players, as are the other high level counters in the table above. If you want to see the selected Memory counters in a custom module in the Profiler window, use the Module Editor to configure the chart.

Detailed view

The Detailed view provides a snapshot of your application’s current state. Click the Take Sample button to capture detailed memory usage for the current target. It takes the Profiler time to get this data, so the Detailed view does not give you real-time details. After the Profiler takes a sample, the Profiler window displays a list view where you can explore your application’s memory usage in more detail.

Enable the Gather object references setting at the top of the module details pane to collect information about what is referencing an object at the time of the snapshot. The Profiler displays this information in the right-hand pane of the window.

The list view divides objects that use memory into the following categories:

• Other: Objects that are neither Assets, GameObjects, or components. This includes information such as the memory Unity uses for different systems.
• Not Saved: Objects marked as DontSave
• Builtin Resources: Unity Editor resources or Unity default resources, such as Shaders you have added to the Always Included Shaders list of the Graphics settings.
• Assets: Assets referenced from user or native code.
• Scene Memory: Objects and attached components.

When you click on a GameObject in the Assets or Scene Memory list, it’s highlighted in the Project or Scene view.

Note: In the Other category, memory reported under System.ExecutableAndDlls is read-only memory. The operating system might discard these pages as needed and later reload them from the file system. This generates lower memory usage, and usually does not directly contribute to the operating system’s decision to close your application if it uses too much memory. Some of these pages might also be shared with other applications that are using the same frameworks.