External annotations
Last modified: 10 August 2022Storing annotations in the source code is not always convenient. For example, if you work on a project in a team where everybody uses different IDEs, if you work with library classes, or if you want to keep your code free from annotations. This is when you can use external annotations.
External annotations are regular annotations that are stored outside your source code in an XML file called annotations.xml.
In code, external annotations are marked with the gutter icon and are highlighted with grey. By default, IntelliJ IDEA displays external annotations in the editor.

Enable external annotations
To use external annotations, you need to enable this option in the settings. If you skip this step, you will be able to annotate library code externally, but you will not be able to use external annotation with your source code.
Press Ctrl+Alt+S to open the IDE settings and select Editor | Code Style | Java | Code Generation.
Select the Use external annotations checkbox.
Apply the changes and close the dialog.
Make an annotation external
To quickly convert a regular annotation to an external annotation, position the caret at it and press Alt+Enter (or click the intention action
icon), and select Annotate externally.
Gif
Add a new annotation
Press Alt+Enter on the element you want to annotate (or click the intention action
icon).
Select Annotate <element> <element name> (for example,
Annotate field 'out'
), and select an annotation.If there is only one annotation you can use, select the Annotate <element> <element name> as @<Annotation> option (for example,
Annotate class 'String' as @Deprecated
).In the next dialog, click Add externally.
Specify a directory where you want to store the file with external annotations (external annotations root).
Each next external annotation within this module will be stored in the same folder. If you have multiple annotation roots, IntelliJ IDEA will ask you which one to use.
Configure annotations root directory
The annotations root directory is a folder where you store external annotations used in the current module of your project. You can change, remove and add a new root:
Press Ctrl+Alt+Shift+S to open the Project Structure dialog.
Go to Modules | Paths.
Locate the External Annotations area, where you can manage external annotations attached to the module.
Annotations can be configured on the project level as well. While in the Project Structure dialog, click SDKs | Annotations.
In case external annotations are added to the elements of the external library of a Maven/Gradle project, the path to the annotations root directory will be stored in Project Structure | Modules | Dependencies in the Annotations list of the Maven/Gradle library.
Hide external annotations
External annotations are displayed in the editor by default. You can hide them from your code:
Press Ctrl+Alt+S and select Editor | Inlay hints | Java.
Clear the External annotations checkbox.
Apply the changes and close the dialog.
When external annotations are hidden, only the icon in the gutter marks their presence in code.
tip
You can also right-click an external annotation, and disable the Show external annotations option.
Download external annotations from Maven
You can store external annotations as Maven artifacts and download them together with a library. To do so, select the Annotations checkbox in the Download library from Maven Repository dialog.

IntelliJ IDEA will search for all artifacts with the annotations
classifier and download them if they are available in the repository.
tip
For more information on downloading a library from Maven, refer to Download a library from Maven
Thanks for your feedback!