You can prevent shader variantsA verion of a shader program that Unity generates according to a specific combination of shader keywords and their status. A Shader object can contain multiple shader variants. More info
See in Glossary from being compiled. This is called stripping. Stripping unneeded variants can greatly reduce build times, file size, shaderA program that runs on the GPU. More info
See in Glossary loading times, and runtime memory usage. In larger projects, or projects with complex shaders, this is a very important consideration.
If you strip a shader variant that a Material needs at runtime, Unity tries to choose a similar shader variant that’s available. To avoid this, use the following approaches:
shader_feature
keyword, don’t use the keyword to change which code branch executes at runtime.The way that you declare shader keywords can limit the number of variants that they produce:
shader_feature
instead of multi_compile
where possible - see conditionals in shaders.multi_compile
.For information on declaring keywords in hand-coded shaders, see Declaring and using shader keywords in HLSL. For information on declaring keywords in Shader Graph, see Shader Graph: Blackboard.
When you declare a keyword, Unity assumes all stages of the shader contain conditional code for that keyword.
You can add the following suffixes to indicate that only certain stages contain conditional code for a keyword, so that Unity doesn’t generate unneeded shader variants.
_vertex
_fragment
_hull
_domain
_geometry
For example, use #pragma shader_feature_fragment RED GREEN BLUE
to indicate that you use the 3 keywords to create conditional code in the fragment stage only.
You can’t add these suffixes to #pragma dynamic_branch
because dynamic_branch
doesn’t create variants.
These suffixes might behave differently or have no effect, depending on the graphics API. For example:
_geometry
and _raytracing
suffixes have no effect on Metal. Metal treats _vertex
, _hull
and _domain
as a single stage.In Unity 2021.3 and above, you can create conditional shader code using a target platform preprocessor macro, so you can limit variants on platforms with limited memory.
The code sample does the following:
SHADER_API_DESKTOP
platform, Unity builds variants for every possible keyword combination.#ifdef SHADER_API_DESKTOP #pragma multi_compile _ RED GREEN BLUE WHITE #else #pragma shader_feature RED GREEN BLUE WHITE #endif
You can use target platform preprocessor macros to select between shader_feature
, multi_compile
and dynamic_branch
. For more information on when to use each type of conditional, see Shader Conditionals.
When you build for console and mobile platforms that have limited memory, you can limit shader variants by only allowing users to switch between a small number of quality settings.
For example, if you use the keywords DYNAMIC_LIGHTING
, SOFT_SHADOWS
and HIGH_QUALITY_LIGHTMAPS
, you can create the following:
DYNAMIC_LIGHTING
.DYNAMIC_LIGHTING
, SOFT_SHADOWS
and HIGH_QUALITY_LIGHTMAPS
.This means Unity won’t create shader variants for DYNAMIC_LIGHTING
when it’s off, or the many different combinations of the 3 keywords being on and off.
You can use target platform preprocessor macros to conditionally create fewer quality settings and fewer variants on platforms with limited memory. For example the following code sample will allow users to switch between 8 permutations of settings on SHADER_API_DESKTOP
platforms, but only 2 on SHADER_API_MOBILE
platforms.
#if SHADER_API_DESKTOP #pragma multi_compile SHADOWS_LOW SHADOWS_HIGH #pragma multi_compile REFLECTIONS_LOW REFLECTIONS_HIGH #pragma multi_compile CAUSTICS_LOW CAUSTICS_HIGH #elif SHADER_API_MOBILE #pragma multi_compile QUALITY_LOW QUALITY_HIGH #pragma shader_feature CAUSTICS // Uses shader_feature, so Unity strips variants that use CAUSTICS if there are no Materials that use the keyword at build time. #endif
There are several places in the Unity Editor UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary where you can configure shader stripping:
In the Graphics Settings window, configure the settings in the Shader stripping section:
Ensure that no unneeded shaders are included in the Always-included shaders setting.
Strip variants relating to GPU instancing, lightmapping, and fog.
In the Built-in Render PipelineA series of operations that take the contents of a Scene, and displays them on a screen. Unity lets you choose from pre-built render pipelines, or write your own. More info
See in Glossary, if it is not important that your Tier settings are different, ensure that they are identical to each other. For more information, see Graphics tiers.
In the Universal Render Pipeline (URP), disable unused features in the URP Asset. For more information, see Shader stripping.
If you use the Universal Render Pipeline you can also do the following:
If you use the High Definition Render Pipeline you can also do the following:
For shader variants that you can’t strip in other ways, you can use the following APIs in an Editor script to perform build-time stripping:
For more information on this subject, refer to Stripping scriptable shader variants
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.