IntelliJ IDEA 2022.1 Help

External annotations

Storing 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 External annotation icon gutter icon and are highlighted with grey. By default, IntelliJ IDEA displays external annotations in the editor.

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.

  1. Press Ctrl+Alt+S to open the IDE settings and select Editor | Code Style | Java | Code Generation.

  2. Select the Use external annotations checkbox.

  3. 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 Intention action icon icon), and select Annotate externally.

    Converting a regular annotation to an external annotation

Add a new annotation

  1. Press Alt+Enter on the element you want to annotate (or click the intention action Intention action icon icon).

  2. Select Annotate <element> <element name> (for example, Annotate field 'out'), and select an annotation.

    Adding a new external 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).

  3. In the next dialog, click Add externally.

  4. 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:

  1. Press Ctrl+Alt+Shift+S to open the Project Structure dialog.

  2. Go to Modules | Paths.

  3. 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:

  1. Press Ctrl+Alt+S and select Editor | Inlay hints | Java.

  2. Clear the External annotations checkbox.

  3. Apply the changes and close the dialog.

When external annotations are hidden, only the External annotation icon icon in the gutter marks their presence in code.

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.

Downloading a library from Maven

IntelliJ IDEA will search for all artifacts with the annotations classifier and download them if they are available in the repository.

Last modified: 10 August 2022