Anyone who has worked on a game has likely encountered situations where the engine repeatedly reimports assets, a seemingly unrelated change triggers a cascade of reimports, or opening a project takes an unexpectedly long time. As projects grow to include thousands of assets, these reimport cycles can dramatically increase iteration times, disrupt workflows, and slow overall team productivity.
Fortunately, Unity offers a range of diagnostic tools that help you understand what’s actually happening under the hood. By using them effectively, you can reduce unnecessary reimports and spend more time building your game instead of waiting on the editor. In this tutorial, we’ll explore some of these tools and how to use them.
What happens during a reimport?
Whenever source and asset files are edited, Unity needs to reimport them and refresh its Asset Database to keep them in sync. By default, Unity performs an Asset Database refresh whenever the editor regains focus. During this process, it scans the Assets and Packages folders for any files that have been added, deleted, or modified.
Unity begins by processing code-related assets, such as scripts, DLLs, and Assembly Definition files, then triggers a Domain Reload. It then proceeds to other asset types, such as textures, audio files, meshes, animation files and so on, compiling a list of all detected changes. Assets whose dependencies have changed are also added to this list and scheduled for reimport, even if the assets themselves were not directly modified.
To reflect these changes in the project, Unity then runs each modified file through its importers. Since the engine typically cannot use source files in their original format, it reads them from disk, creates a metadata file describing its import settings, and generates an internal representation stored in the Library folder, in formats optimized for the editor and the target platform.
The Library folder functions primarily as a local cache and is normally excluded from version control. As a result, when you open a project for the first time, or after deleting the Library folder, Unity must reimport all assets, which can be a lengthy process.
Inspecting the Import Activity window
The Import Activity window lets you see a list of the most recent imports, along with diagnostic information to understand what triggered the import, its duration, and so on. You can access it via Window > Analysis > Import Activity.
On the right, the window will show a quick overview of the assets that had the longest import time, and the assets with the most dependencies. You should prioritise those to reduce your overall import time and have faster iterations in your project.
On the left you’ll see a list of all the assets that have been (re)-imported. You can select one to have more information, including a list of its dependencies, and the reason why the import was triggered. This can be because no previous revision was found (so a first import, or the related artifact in the library was deleted), a change in their custom or dynamic dependencies, a Unity version upgrade resulting in an importer upgrade, or a build target change, among others.
It will also point you to the produced artifact in the library folder. In some cases, a single source asset will result in multiple files being generated. This is for example the case when importing .fbx models that might contain materials and animations. You can see that in the Produced Files/Artifacts pane.
You can also select an asset within your Project view, right click on it and select “View in Import Activity window”, which will directly point you to its latest import event.
Reimports can also happen as a result of changes to the asset dependencies, either static (such as asset name, or build target change) or dynamic (assets referencing other assets). The dependencies resolution logic was significantly overhauled from Unity 6.4 onwards, resulting in fewer dependencies and faster import times.
You can read more about it here.
Search Indexing Importers
In some cases, you will see reimports in the Import Activity window where the reason looks like “ASIEI03”. These are Search Index Entry importers, used to support the Unity Search functionality.
They normally are very fast and do not affect import times significantly. You can optionally disable these, from Unity 6.3 onwards, by going to Preferences > Search > Indexing and toggling Index on Editor Startup.
Inspecting the Editor Logs
Whenever assets are imported, Unity will print some diagnostic info in the editor logs. This is similar to what you can see from the Activity Import window, but in text form.
Here are a few examples:
[Worker7] Start importing Assets/Textures/hero.png using Guid(ae35ctf46db9fd442b94a73df0ec0f44) Importer(2089858483,0ecaa5967403d0e2aa24f35e1b516d23)
Done ondemand importing asset: 'Assets/Textures/hero.png' (artifact id: '4fead12a87251aa702d2e109bfb6181b')
Done importing asset: ‘Assets/Textures/hero.png’ (target hash: ‘b6abac4492f6da0253684d7b2f48c6e3’) in 76.646241 second
Determining why an asset is marked as changed
Whenever an asset is modified, either externally, within the editor, or from a custom editor script, it is marked as dirty. That means that Unity will need to reimport the asset to have an accurate representation of it.
While the Import Activity window provides some insights on this, with a reason for the asset reimport, in some cases it can be tricky to understand why an asset was marked as dirty.
In order to do so, you can use the ObjectSetDirty Diagnostic Flag. When that is enabled, Unity will print in the Editor logs the callstack that led to the object becoming dirty.
You can enable it by going to Preferences > Diagnostics > Core > ObjectSetDirty. Make sure to restart the Editor after toggling it.
When the flag is enabled, you will start seeing relevant logs whenever an object’s dirty count is increased. They will include, in order, the dirty count, their instance ID, the object name, and its type.
Increment Dirty(3) : [-3808] Sphere (GameObject)
Similarly, when an object dirty count is cleared, normally as a result of a reimport, it will be shown in the logs.
Clear Dirty(0) : [942] UIMask (Sprite)
Make sure to set Stack Trace Logging to Full for All logs, this way you’ll see the full stacktrace with a clear indication of what is setting the object as dirty.
For example, let’s look at these logs:
Increment Dirty(1) : [17448] HeroPrefab (GameObject)1,int,string)
#0 PlatformStacktrace::GetStacktrace(int)
#1 DebugStringToFile(DebugStringToFileData const&)
#2 Object::IncrementPersistentDirtyIndex()
#3 Object::SetDirty()
#4 GameObject::SetLayer(int)
#5 (Mono JIT Code) (wrapper managed-to-native) UnityEngine.GameObject:set_layer_Injected (intptr,int)
#6 (Mono JIT Code) UnityEngine.GameObject:set_layer (int)
#7 (Mono JIT Code) [SceneModeUtility.cs:311] UnityEditor.SceneModeUtility:SetLayer (System.ReadOnlySpan
[…]`
We can determine that the asset was marked as dirty because I changed its layer.
You can learn more about this diagnostic flag here.
AssetDatabase API Operations Batching
Database Refresh operations are often a result of Editor API calls, such as AssetDatabase.CopyAsset and AssetDatabase.DeleteAsset. By default, Unity executes each line and performs a full refresh for that Asset before moving to the next line. This is not ideal when your script modifies multiple assets, as it is often the case.
To avoid this, you can call AssetDatabase.StartAssetEditing, which will suspend importing while you interact with the Asset Database, allowing you to process a batch of asset operations. Then, you call AssetDatabase.StopAssetEditing to tell Unity you are done.
Here is an example:
csharp
try
{
AssetDatabase.StartAssetEditing();
AssetDatabase.MoveAsset("Assets/hero.png", "Assets/Textures/hero.png");
AssetDatabase.DeleteAsset("Assets/Old/placeholder.png");
}
finally
{
AssetDatabase.StopAssetEditing();
}
Unity keeps an internal counter for these calls. This means that you need to match the amount of StartAssetEditing and StopAssetEditing calls, otherwise the AssetDatabase will stay disabled and might become unresponsive.
Parallel Importing
Since Unity 2022, you can run parallel imports for certain types of assets, significantly speeding up the import process.
To enable that, go to Project Settings > Editor > Asset Pipeline and tick Parallel Import.
Parallel importing is supported for Textures, Models, and Audio assets. Other types of assets will still be imported sequentially.
When that is enabled, Unity will spread the import workload over multiple threads. You can optionally specify how many workers you’d like Unity to use for importing, as well as setting up their standby behaviour, using the options just below. Unity will then aim to follow those settings, but the actual numbers of workers might be different depending on system availability. The default values are derived from Settings > Asset Pipeline > Import Worker Count % and are suitable for most scenarios.
Parallel Import can cause unexpected issues when you have custom importers in your project, for example if they create new assets, change Editor settings, modify static variables, or if they rely on a certain execution order which might lead to race conditions. In those cases, you should aim to rewrite your importer logic to be self-contained and Thread-safe.
Disabling Assets Auto Refresh
Unity refreshes the asset library whenever the editor regains focus, automatically reimporting changed assets, as well as detecting added or deleted assets.
We can change this behaviour by going to Preferences > Asset Pipeline and setting Auto Refresh to Disabled.
When that is disabled, you will need to manually refresh the Asset Database via the Assets > Refresh menu, or via the related AssetDatabase.Refresh API call.
Asset Database Refresh operations can also be initiated by your IDE. Rider, for example, triggers them whenever you save or add a new script file, pull from version control, or run unit tests. You can prevent Rider from requesting a refresh by going to Languages & Frameworks > Unity Engine > General and disabling “Automatically refresh assets in Unity”.
Compressing Textures on Import
Whenever you open a new project, or add new texture assets to an existing one, Unity automatically compresses those textures during the import process. This ensures that what you see in the editor is closer to what you would see in the game build. Compressing textures can take a considerable amount of time though, particularly in large projects with a lot of assets and very large image source files, resulting in very long import times.
You can disable this by going to Preferences > Asset Pipeline > Compress Textures on Import and toggling it off.
This is recommended when you need to reduce long import times. When that is disabled, Unity will keep textures in an uncompressed format while working in the editor.
Textures will then be compressed when making a build, resulting in longer build time. This might not be relevant if you don’t intend to make local builds, for example if you rely on a CI/CD pipeline.
In some cases, you might want to disable this before you actually open the editor, for example to make the initial project import faster. You can do so by navigating to UserSettings/EditorUserSettings.asset and setting m_CompressAssetsOnImport: 0.
You can read more about Texture import settings, including how to reduce their compressing time and memory footprint, here.
Top comments (0)