Unity Meta File FAQ
Unity’s .meta files are one of the most consistent sources of confusion and anguish for Unity developers.
We wrote this FAQ to answer the most common questions that we get asked about meta files. Hopefully it will help save you time and effort debugging Asset and meta file issues so you can focus on building great software.
While this FAQ is focussed on providing succinct answer to common questions, it forms part of the larger Unity Meta File Guide, which covers the subject in more detail. Many of the answers below include links to more detailed articles where you can dig deeper.
Got a question that we don’t answer?
Send it over and we’ll see what we can do to answer it for you.
What is a Unity meta file?
The Unity Editor creates meta files to track the identity and settings of every Asset in your project.
Meta files are named after the Asset they are associated with. For instance, a texture Asset with the filename Explosion.png would have a meta file named Explosion.png.meta
This article covers Unity’s Asset and meta files in more detail.
What is a Unity GUID?
The Unity Editor uses 32-digit hexadecimal strings called Globally Unique Identifiers (GUIDs) to identify Assets within a project.
Each Asset is assigned a GUID which is stored in that Asset’s .meta file. A Unity GUID looks something like this de9a32f15f2628044842629a83d3d974
Unity uses GUIDs to track references between Assets. If an Asset’s GUID changes, all references to that GUID will become broken.
You can read more about how Unity uses GUIDs to track references here. To learn how to avoid broken references head over to Avoiding Broken References in Unity Projects
Should I add Unity’s meta files to version control?
Yes. Unity’s .meta files form a critical part of your project and hence should be committed to your Version Control System.
Meta files are used to store the settings for each Asset along with a Globally Unique Identifier (GUID) that is used to track references between Assets, for instance when a Material Asset references a Texture Asset.
Learn how to version control your Unity project using Git in this how-to guide.
Once you have added your project’s meta files to version control, you need keep them synchronized with the Assets that they relate to. If you are using git, our MetaBuddy plugin for Unity helps you do this every time you commit.
Are Unity meta files just used for version control?
No. Unity meta files contain valuable information about the Assets in your project. You should check them into your version control system (VCS).
If you omit the .meta files, the version of your project in source control will be incomplete and broken, with missing settings, and broken references between objects.
You can learn how to setup a Unity project correctly using Git and GitHub in this how-to guide.
Should I setup my .gitignore file to exclude Unity meta files?
No. Unity meta files contain valuable information about the assets in your project. You should add them to your git repository.
See our how to add a Unity Project to GitHub article to learn what a .gitignore file should contain for a Unity project.
Should I choose hidden or visible meta files when using Unity with a Version Control System?
Configure Visible Meta Files in Unity’s Project Settings when using Unity with a version control system like git or Subversion. By making meta files visible, you can add them to your VCS along with the rest of your Unity project.
At the time of writing (February 2019) Unity uses Visible Meta Files by default for newly created projects.
To turn them on for legacy projects chose Edit → Project Settings → Editor from the Unity Editor’s application menu. Then choose Visible Meta Files from the Version Control dropdown.
What Asset Serialization Mode should I choose when using Unity with a Version Control System?
Unity’s Asset Serialization Mode controls how meta files and Scenes are stored on your hard drive. You should set Unity to use the Force Text setting for Asset Serialization Mode when working with a VCS.
In this mode, Unity stores Assets and Scenes in a text-based YAML format. This makes it possible to merge conflicts between differing versions of the file.
At the time of writing (February 2019) Unity uses Force Text as the default for new projects.
To set this mode for legacy projects chose Edit → Project Settings → Editor from the Unity Editor’s application menu. Then choose Force Text from the Asset Serialization Mode dropdown.
How does Unity track references between Assets?
Unity uses Globally Unique Identifiers (GUIDs) to track references between Assets. Each has Asset in a Unity project has a GUID, which is stored in the .meta file for that Asset.
When an Asset (for instance a Material) in your project references an another Asset that it depends on (for instance a Texture) it points that asset by GUID. ie. The Material stores a copy of the Texture’s GUID.
The crucial thing to recognise here is that the name of Asset is immaterial to the Unity Editor, it only cares about the GUID for referencing purposes. You can find more details in this guide to avoiding broken references
How do avoid I broken references and missing meta files in Unity?
Modifying Assets outside Unity Editor is the more common cause of broken references and missing meta files.
The easiest way to avoid this is to always create, move and rename your Assets using the Unity Editor.
When you do this, the Editor manages references and meta files behind the scenes on your behalf, avoiding breakages.
Another common cause is deleting and re-adding Assets in the Editor in order to modify their contents.
See Avoiding Broken References to learn the common causes of Unity project breakage and how to avoid them.
Why do meta files keep appearing unexpectedly in my Unity project?
If you find that mystery .meta files are appearing in your project’s Assets/ directory, this usually means that a file has been added to the Assets/ directory from outside the Unity Editor.
When the Editor detects a new file in the Assets folder that doesn’t have a companion meta file, it attempts to that file into your project as a new Asset. This creates a meta file to hold the Globally Unique Identifier (GUID) and settings for the newly added Asset.
For instance, if you copy an image file Explosion.png to the Assets folder, the Editor will import it as a texture, creating a meta file Explosion.png.meta alongside it.
A common cause of mystery meta files is when developer forgets to include a meta file when adding a new asset to version control. This often means that any references to the new asset will be silently broken.
You can use a tool like MetaBuddy or a pre-commit checklist to avoid this common problem.
What causes ‘The referenced script (Unknown) on this Behaviour is missing!’ error message in Unity?
The Unity Editor shows this message when you enter Play mode in a project containing a broken reference to a Script Asset.
This usually means that the Script Asset has been deleted or its GUID has been inadvertently changed.
While this error message doesn’t give any information about which GameObject in your Scene has the broken reference it is often accompanied by a 'The referenced script on this Behaviour (Game Object ?) is missing!' error message which provides more information on the source of the error.
See our avoiding broken references article to learn how broken references can be avoided in Unity projects.
What causes ‘The referenced script on this Behaviour (Game Object ?) is missing!’ error message in Unity?
The Unity Editor shows this message when you enter Play mode in a project containing a broken reference to a Script Asset.
This usually means that the Script Asset has been deleted or its GUID has been inadvertently changed.
Clicking on this error message in the Console pane will highlight the GameObject holding the broken reference in the Hierarchy pane.
Head over to Avoiding Broken References to learn how to avoid the broken references that cause this error message.