Unity Addressables
Unity Optimization
Memory Management
AssetBundles
Mobile Game Development
Unity WebGL
Unity C#

Unity Addressables Optimization: Memory Management, Handle Lifecycle & Bundle Packing

14 min read
Eshan Naithani

Unity's Addressables system decouples what an asset is from where and how it is stored and loaded. Instead of hardcoding direct Inspector references into scenes or placing gigabytes of prefabs inside Assets/Resources/, Addressables lets you load assets asynchronously by string address or type-safe AssetReference, pack content into local or remote AssetBundles, and manage memory deterministically via reference counting.

However, migrating a project to Addressables does not automatically lower RAM consumption or speed up loading times. In production audits across mobile and WebGL titles, poorly configured Addressable groups and leaked AsyncOperationHandle structs are among the top causes of Out-Of-Memory (OOM) crashes and asset duplication.

This guide covers how the Addressables reference-counting architecture actually works under the hood, why assets remain in memory after calling Release(), how to structure bundle packing and remote catalogs, and verified C# patterns for leak-free asset loading.

Looking for a full engine-wide optimization pass? Pair this guide with our Unity 6 Mobile Game Optimization Guide and Unity WebGL Performance Guide, or explore our Unity Game Development Services.


1. How Addressables Reference Counting & Bundle Unloading Work

To optimize Addressables memory, you must understand the two-layer relationship between Individual Assets and their Containing AssetBundles:

  1. Asset-Level Reference Count: Every call to Addressables.LoadAssetAsync<T>() or Addressables.InstantiateAsync() increments the internal reference count for that specific asset by +1. Every matching call to Addressables.Release(handle) or Addressables.ReleaseInstance(instance) decrements it by -1.
  2. AssetBundle-Level Reference Count: An AssetBundle stays mounted in memory as long as at least one asset inside that bundle (or another bundle that depends on it) has a reference count greater than 0. Only when every asset in the bundle drops to a reference count of 0 does Addressables automatically unload the underlying AssetBundle (AssetBundle.Unload(true)), freeing both the serialized bundle header and all native texture/mesh/audio memory inside it.

Why Loaded Assets Remain in Memory After Addressables.Release()

If the Unity Memory Profiler shows textures or meshes still residing in RAM after you release an AsyncOperationHandle, one of four architectural issues is occurring:

Root CauseWhat Happens in MemoryHow to Fix It
1. Unbalanced Load / Release CallsCalling LoadAssetAsync 3 times and Release twice leaves RefCount = 1. The handle never unloads.Store a single AsyncOperationHandle<T> per system or release every handle stored in a list on scene teardown.
2. Co-Packed "Immortal" AssetsPacking a persistent HUD sprite in the same Pack Together group as a 40 MB Level 1 environment keeps the entire Level 1 bundle mounted for the whole session.Isolate persistent global UI/audio into a dedicated Global_Core group and pack level-specific environments per level or per biome.
3. Implicit Duplicate DependenciesTwo prefabs in Group_A and Group_B both reference a non-Addressable SharedCharacter.mat. Unity silently bakes a full copy of SharedCharacter.mat and its 4K textures into both bundles.Run the Addressables Analyze tool (Check Duplicate Bundle Dependencies) and move shared materials/textures into an explicit Shared_Assets Addressable group.
4. Mixing LoadAssetAsync with Object.InstantiateLoading a prefab with LoadAssetAsync, discarding the struct handle without storing it, and calling Destroy(spawnedInstance) destroys the scene clone while leaking the loaded prefab asset forever.Always retain the AsyncOperationHandle<GameObject> field and call Addressables.Release(handle) in OnDestroy(), or use Addressables.InstantiateAsync paired with Addressables.ReleaseInstance.

2. Release vs. Unload: Choosing the Correct C# API

Understanding the exact contract of each cleanup method prevents both memory leaks and accidental missing-reference exceptions:

  • Addressables.Release(AsyncOperationHandle<T> handle): Decrements the reference count of an operation handle returned by LoadAssetAsync, LoadAssetsAsync, or DownloadDependenciesAsync. Always prefer passing the typed AsyncOperationHandle<T> struct rather than the raw loaded UnityEngine.Object.
  • Addressables.ReleaseInstance(GameObject instance) / Addressables.ReleaseInstance(AsyncOperationHandle<GameObject> handle): Specifically destroys a GameObject created via Addressables.InstantiateAsync and decrements its Addressables reference count. Note: Addressables.InstantiateAsync carries slight CPU overhead compared to LoadAssetAsync + Object.Instantiate when spawning hundreds of projectiles per second. For high-frequency combat objects (bullets, VFX, sorting items), load the prefab once with LoadAssetAsync<GameObject>(), spawn pooled clones with Object.Instantiate(), and call Addressables.Release(prefabHandle) when leaving the level.
  • Addressables.UnloadSceneAsync(AsyncOperationHandle<SceneInstance> sceneHandle): Unloads an additive scene loaded via Addressables.LoadSceneAsync and decrements the reference counts of all Addressable bundles tied to that scene (see our Unity 6 Scene Loading Optimization Guide for full additive scene transition patterns).
  • Resources.UnloadUnusedAssets(): Forces a full mark-and-sweep scan across all Unity objects in the engine. It is not required to unload properly released Addressable bundles (which unload deterministically when bundle ref-count hits 0), and should only be called during major screen transitions if legacy non-Addressable references are used.

3. Verified Unity C# Pattern: Safe Handle Lifecycle Management

Never fire-and-forget Addressables.LoadAssetAsync without storing the returned AsyncOperationHandle<T> struct. In addition, always guard against component destruction during an in-flight async load: if a player closes a menu or switches scenes before await handle.Task completes, you must immediately release the handle upon completion so it does not leak in the background.

CSHARP
using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

namespace MyGame.AssetManagement
{
    public sealed class AddressableLifecycleLoader : MonoBehaviour
    {
        [Header("Type-Safe Asset References")]
        [SerializeField] private AssetReferenceGameObject environmentPrefabRef;
        [SerializeField] private AssetReferenceT<AudioClip> ambientMusicRef;

        private AsyncOperationHandle<GameObject> _environmentHandle;
        private AsyncOperationHandle<AudioClip> _musicHandle;
        private GameObject _spawnedEnvironment;
        private bool _isDestroyed;

        private readonly List<GameObject> _trackedInstances = new List<GameObject>();

        private async void Start()
        {
            await LoadLevelAssetsAsync();
        }

        public async Task LoadLevelAssetsAsync()
        {
            if (environmentPrefabRef != null && environmentPrefabRef.RuntimeKeyIsValid())
            {
                _environmentHandle = environmentPrefabRef.LoadAssetAsync<GameObject>();
                await _environmentHandle.Task;

                // Guard: If the MonoBehaviour was destroyed while awaiting disk/network IO, abort cleanly
                if (_isDestroyed)
                {
                    ReleaseHandleIfValid(ref _environmentHandle);
                    return;
                }

                if (_environmentHandle.Status == AsyncOperationStatus.Succeeded)
                {
                    // Instantiate using standard Unity Instantiate while holding a single handle for the prefab
                    _spawnedEnvironment = Instantiate(_environmentHandle.Result, transform);
                }
                else
                {
                    Debug.LogError($"[Addressables] Failed to load environment: {_environmentHandle.OperationException}");
                }
            }

            if (ambientMusicRef != null && ambientMusicRef.RuntimeKeyIsValid())
            {
                _musicHandle = ambientMusicRef.LoadAssetAsync<AudioClip>();
                await _musicHandle.Task;

                if (_isDestroyed)
                {
                    ReleaseHandleIfValid(ref _musicHandle);
                    return;
                }
            }
        }

        /// <summary>
        /// Example helper for one-off UI popups or characters spawned via InstantiateAsync.
        /// </summary>
        public async Task<GameObject> SpawnTrackedInstanceAsync(string addressKey, Transform parent)
        {
            AsyncOperationHandle<GameObject> handle = Addressables.InstantiateAsync(addressKey, parent);
            GameObject instance = await handle.Task;

            if (_isDestroyed)
            {
                if (instance != null)
                {
                    Addressables.ReleaseInstance(instance);
                }
                return null;
            }

            if (handle.Status == AsyncOperationStatus.Succeeded && instance != null)
            {
                _trackedInstances.Add(instance);
                return instance;
            }

            return null;
        }

        private void OnDestroy()
        {
            _isDestroyed = true;

            // 1. Destroy any clones created via standard Instantiate() first
            if (_spawnedEnvironment != null)
            {
                Destroy(_spawnedEnvironment);
                _spawnedEnvironment = null;
            }

            // 2. Release all instances spawned via Addressables.InstantiateAsync()
            for (int i = _trackedInstances.Count - 1; i >= 0; i--)
            {
                if (_trackedInstances[i] != null)
                {
                    Addressables.ReleaseInstance(_trackedInstances[i]);
                }
            }
            _trackedInstances.Clear();

            // 3. Deterministically release stored asset handles so the AssetBundle ref count reaches 0
            ReleaseHandleIfValid(ref _environmentHandle);
            ReleaseHandleIfValid(ref _musicHandle);
        }

        private static void ReleaseHandleIfValid<T>(ref AsyncOperationHandle<T> handle)
        {
            if (handle.IsValid())
            {
                Addressables.Release(handle);
                handle = default;
            }
        }
    }
}

4. Addressable Group Packing & Compression Architecture

How you partition assets into Addressable Groups in Window > Asset Management > Addressables > Groups directly determines both disk I/O overhead and peak RAM footprint.

Selecting the Right Bundle Mode (BundledAssetGroupSchema)

Every Addressable Group uses a BundledAssetGroupSchema with three packing modes:

Bundle ModeWhen to Use ItMemory & I/O Trade-off
Pack TogetherCohesive asset sets loaded and unloaded at the exact same time (e.g., UI_MainMenu, Core_Shaders)Minimizes total .bundle file count and catalog metadata size, but all assets must reach RefCount = 0 before the bundle unloads.
Pack SeparatelyLarge, independent assets loaded one at a time (e.g., 50 distinct boss prefabs, individual high-res character skins, or streamed audio tracks)Allows each asset's underlying bundle to unload immediately when released, preventing bundle-level memory retention. Do not use for thousands of tiny sprites, as excessive bundle files increase catalog size and file-handle overhead.
Pack Together By LabelMulti-level games where assets are tagged Level_01, Level_02, Biome_DesertAutomatically splits a single logical group into one AssetBundle per label without manually creating 100 separate groups in the Inspector.

Compression Settings: Local vs. Remote Groups

  • Local Built-In Groups (Build & Load Paths: Local): Always set Compression to LZ4. LZ4 is chunk-based, allowing Unity to decompress only the 64 KB–128 KB chunks corresponding to the requested asset without decompressing the entire AssetBundle into memory. Never use LZMA for local groups packaged inside an APK/IPA, as Android and iOS archives already compress the binary and LZMA forces whole-bundle decompression on load.
  • Remote CDN Groups (Build & Load Paths: Remote): Use LZ4 for most mobile and WebGL streaming workflows, or LZMA only when raw CDN bandwidth is severely constrained and you have Use Asset Bundle Cache enabled (Unity downloads the LZMA stream once and re-compresses it into chunk-based LZ4 inside the device's local cache).
  • Disable AssetBundle Sub-Object Type Trees Where Appropriate: In BundledAssetGroupSchema advanced settings, keep internal bundle naming to Filename or File Guid and enable Include Addresses in Catalog only for groups that you actually look up by string address at runtime. Using AssetReference in C# avoids string-lookup bloat inside the binary catalog.

5. Eliminating Duplicate AssetBundle Dependencies with the Analyze Tool

One of the most insidious memory bugs in Unity occurs when two Addressable prefabs in different groups reference a common non-Addressable asset—such as a shared UI atlas, character shader, or PBR material. Because neither bundle knows whether the other will be present at runtime, Unity's build pipeline duplicates the shared asset into both AssetBundles.

When both bundles are loaded simultaneously at runtime:

  1. Two separate copies of the texture or mesh are deserialized into native memory.
  2. GPU VRAM consumption doubles for those shared assets.
  3. Instantiated prefabs from Group A and Group B fail to batch together because they point to two distinct Material instance IDs in memory.

Step-by-Step Fix Using Addressables Analyze

  1. Open Window > Asset Management > Addressables > Analyze.
  2. Expand Analyze Rules > Fixable Rules > Check Duplicate Bundle Dependencies.
  3. Click Analyze Selected Rules.
  4. Review the output tree: every asset listed appears in two or more bundles.
  5. Either click Fix Selected Rules (which automatically creates a Duplicate Asset Isolation group with LZ4 compression) or manually organize shared materials, shaders, and sprite atlases into a dedicated Shared_Dependencies group before building.

For a deeper look at migrating legacy AssetBundle pipelines to LiveOps-ready Addressables, check out our 3-part architecture series:


6. Remote Catalogs, Caching & Pre-Download Workflows

When delivering seasonal events, extra puzzle packs, or heavy 3D levels over a CDN, never force players to wait on a frozen frame while a 30 MB remote bundle downloads mid-gameplay. Use GetDownloadSizeAsync and DownloadDependenciesAsync during a loading screen or lobby check to pre-warm the local AssetBundle cache:

CSHARP
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.AddressableAssets.ResourceLocators;
using UnityEngine.ResourceManagement.AsyncOperations;

namespace MyGame.AssetManagement
{
    public static class RemoteContentUpdater
    {
        /// <summary>
        /// Checks if remote catalogs have updated on the CDN and downloads any changed bundles for a given label.
        /// </summary>
        public static async Task<bool> CheckAndDownloadLabelAsync(
            string contentLabel,
            IProgress<float> downloadProgress = null)
        {
            // 1. Check if a newer remote catalog hash exists on the CDN
            AsyncOperationHandle<List<string>> checkHandle = Addressables.CheckForCatalogUpdates(false);
            List<string> catalogsToUpdate = await checkHandle.Task;

            if (checkHandle.Status == AsyncOperationStatus.Succeeded &&
                catalogsToUpdate != null &&
                catalogsToUpdate.Count > 0)
            {
                AsyncOperationHandle<List<IResourceLocator>> updateHandle =
                    Addressables.UpdateCatalogs(catalogsToUpdate, false);
                await updateHandle.Task;
                Addressables.Release(updateHandle);
            }
            Addressables.Release(checkHandle);

            // 2. Query how many bytes are not yet cached on disk for this label
            AsyncOperationHandle<long> sizeHandle = Addressables.GetDownloadSizeAsync(contentLabel);
            long bytesToDownload = await sizeHandle.Task;
            Addressables.Release(sizeHandle);

            if (bytesToDownload <= 0)
            {
                downloadProgress?.Report(1f);
                return true; // Already cached locally
            }

            Debug.Log($"[Addressables] Downloading {bytesToDownload / (1024f * 1024f):F2} MB for '{contentLabel}'...");

            // 3. Download dependencies into the local bundle cache and release the download operation handle immediately
            AsyncOperationHandle downloadHandle = Addressables.DownloadDependenciesAsync(contentLabel, false);
            while (!downloadHandle.IsDone)
            {
                DownloadStatus status = downloadHandle.GetDownloadStatus();
                downloadProgress?.Report(status.Percent);
                await Task.Yield();
            }

            bool succeeded = downloadHandle.Status == AsyncOperationStatus.Succeeded;
            Addressables.Release(downloadHandle);
            return succeeded;
        }
    }
}

[!TIP] Unity WebGL Caching Nuance: On WebGL, Caching.ClearCache() and standard file-system bundle caching behave differently because browsers restrict raw disk access. Unity WebGL stores cached AssetBundles inside the browser's IndexedDB via Data Caching or custom UnityCache configurations. See our Unity WebGL Performance Guide for browser-specific caching limits.


7. Profiling Addressables with the Profiler Module & Memory Profiler

Never guess whether a bundle unloaded—verify it in the Unity Profiler:

  1. Enable Addressables Profiler Events: Select Assets/AddressableAssetsData/AddressableAssetSettings.asset in the Project window and check Send Profiler Events under Diagnostics.
  2. Use the Addressables Profiler Module (Unity 6 / Addressables 1.21+) or Event Viewer: Open Window > Analysis > Profiler (and add the Addressables Profiler module) or Window > Asset Management > Addressables > Event Viewer.
    • Inspect live Reference Counts for every loaded AssetBundle, Asset, and Scene.
    • When transitioning from Gameplay back to the Main Menu, verify that level-specific bundles drop to RefCount = 0 and disappear from the active list.
  3. Cross-Check with the Unity Memory Profiler Package: Capture two snapshots (Before Level Load and After Returning to Main Menu) in Window > Analysis > Memory Profiler. Diff the two snapshots under Unity Objects > Texture2D / Mesh / AudioClip to confirm zero orphaned native allocations remain. For a step-by-step walkthrough of snapshot diffing, read our Unity Mobile Memory Profiling & Leak Fixing Guide.

Frequently Asked Questions


Need help architecting or optimizing your Unity mobile game? Let's discuss your technical roadmap.

Share this article

Get Practical Unity Development Insights

Technical guides on Unity performance, AI gameplay systems, mobile monetization, and game development.

Unsubscribe at any time. Your data is never shared.

Recommended Reading

More articles in Unity Addressables