Configure C/C++ Include Cleanup in Visual Studio

Starting with 17.8 Preview 1, Visual Studio can clean up your #includes to improve the quality of your C and C++ code in the following ways:

• Offers to add header files for code that compiles only because a needed header file is included indirectly by another header file.
• Offers to remove unused header files--improving build times.

This article describes how to configure Include Cleanup in Visual Studio. For more information about Include Cleanup, see C/C++ Include Cleanup overview.

Turn on Include Cleanup

The Include Cleanup feature is on by default. If it isn't active, you can turn it on via Tools > Options > Text Editor > C/C++ > Code Cleanup and select Enable #include cleanup.

Then use the dropdowns to configure how you want to be notified about opportunities to add indirect headers or remove unused headers:

The Enable # include cleanup checkbox is checked. The dropdowns for Remove unused includes suggestion level, and Add missing includes suggestion level, are shown. The contents of the dropdown are shown, which are: **Refactoring only**, **Suggestion**, **Warning**, and **Error**. The **Remove unused includes suggestion level** dropdown offers the same options but also adds dimmed.

The meanings of the suggestion level options are:

Refactoring only: Include Cleanup offers actions you can take through the quick action menu when you hover the mouse pointer over an #include, or place the cursor on the #include line and press Ctrl+period:

When hovering the cursor over # include iostream, a light bulb appears with the text that # include iostream isn't used in this file."

Suggestion, Warning, Error: Include Cleanup offers actions it can take via suggestions, warnings, or errors in the Error List window. You determine which. In the following screenshot of the Error List, Include Cleanup is configured to show unused headers with a warning. Ensure that Build + Intellisense is selected in the dropdown filter so that you can see the Include Cleanup output:

The dropdown filter is set to Build + IntelliSense. A warning is visible: VCIC002 - #include < iostream > isn't used in this file."

Dimmed

Include Cleanup shows unused headers by dimming the line of the unused header file in the code editor. Hover your cursor over the dimmed #include to bring up the quick action menu and choose Show potential fixes, or click on the light bulb dropdown, to see actions related to the unused file.

The line for #include < iostream > is dimmed because the line of code that uses iostream is commented out. That line of code is // std::cout << "charSize = " << charSize; The quick action menu is also visible for this line. It says the #include < iostream > isn't used in this file, and has a link to Show potential fixes.

Configure Include Cleanup with .editorconfig

There are more options for configuring Include Cleanup such as excluding specified includes from cleanup suggestions, indicating that some header files are required so that the tool doesn't mark them as unused, and so on. These options are defined in an .editorconfig file, that you can add to your project to, among other things, enforce consistent coding styles for everyone that works in the codebase. For more information about adding an .editorconfig file to your project, see Create portable, custom editor settings with EditorConfig.

The .editorconfig settings that you can use with Include Cleanup are:

Setting	Values	Example
cpp_include_cleanup_add_missing_error_tag_type Sets the error level of add transitive include messages.	none suggestion warning error	cpp_include_cleanup_add_missing_error_tag_type = suggestion
cpp_include_cleanup_remove_unused_error_tag_type Sets the error level of remove unused include messages.	none suggestion warning error dimmed	cpp_include_cleanup_remove_unused_error_tag_type = dimmed
cpp_include_cleanup_excluded_files Excludes the specified files from Include Cleanup messages. You won’t get a suggestion related to the header at all, whether to add it or that it's unused.	filename	cpp_include_cleanup_excluded_files = vcruntime.h, vcruntime_string.h
cpp_include_cleanup_required_files Specify that usage of file1 requires file2. For example, specify that if you use atlwin.h that altbase.h must also be included.	file1:file2	cpp_include_cleanup_required_files = atlwin.h:altbase.h, atlcom.h:altbase.h
cpp_include_cleanup_replacement_files Replaces file1 with file2 during Include Cleanup processing. For example, you may prefer using cstdio over stdio.h. If you have a file with both #include <cstdio> and #include <stdio.h> and you consume content only from stdio.h, with this setting Include Cleanup will tell you to remove stdio.h because it replaced the usage of cstdio with stdio.h during processing. If you don't use the contents from either, Include Cleanup will tell you to remove both.	file1:file2	cpp_include_cleanup_replacement_files = stdio.h:cstdio,stdint.h:cstdint
cpp_include_cleanup_alternate_files Don't generate a message for indirect include file2 if file1 is included. For example, if you #include <windows.h> and are only using something from its indirectly included header winerror.h, Include Cleanup won't prompt to add winerror.h. Useful when you prefer to include a facade header file instead of the indirect includes it contains.	file1:file2	cpp_include_cleanup_alternate_files = windows.h:winerror.h, windows.h:minwindef.h

See also

C/C++ Include Cleanup overview
Include Cleanup messages