IntelliJ IDEA 2020.2 Help

Shared indexes

One of the possible ways of reducing the indexing time is by using shared indexes. Unlike the usual indexes that are built locally, shared indexes are generated once and are later reused on another computer whenever they are needed.

IntelliJ IDEA can connect to the dedicated resource for downloading shared indexes for your JDK and can build shared indexes for the code in your project. Whenever IntelliJ IDEA needs to re-index your application, it will use the available shared project and JDK indexes and will build local indexes for the rest of the project. Normally, this is faster than building local indexes for the entire application from scratch.

Install the Shared Indexes plugin

To be able to use shared indexes, the Shared Indexes plugin must be installed and enabled. The plugin is bundled and enabled by default in IntelliJ IDEA Ultimate. If you use IntelliJ IDEA Community, install the plugin from the repository.

Install the Shared Indexes plugin

  1. In the Settings/Preferences dialog Ctrl+Alt+S, select Plugins.

  2. Switch to the Marketplace tab, type Shared Indexes and click Install.

  3. Apply the changes and close the dialog. Restart the IDE if prompted.

Shared JDK indexes

JDK indexes are built by JetBrains and are stored on a dedicated CDN resource. When you open a project, IntelliJ IDEA shows you a notification prompting you to enable automatic downloading of JDK indexes.

If you miss the notification, go to Settings/Preferences | Tools | Shared Indexes. Select the Download automatically option to silently download JDK indexes whenever they are needed or select Ask before download if you want to manually allow every download.

Shared indexes

JDK indexes will be downloaded to the index/shared_indexes in the IDE system directory. After that, IntelliJ IDEA will be using the suitable indexes whenever they are needed.

Export JDK indexes from the command line

Export shared indexes for a Java Development Kit (JDK) of a specific version.

You can find the script for running IntelliJ IDEA in the installation directory under bin. To use this script as the command-line launcher, add it to your system PATH as described in Command-line interface.

Syntax
idea.bat dump-shared-index jdk --jdk-home=<path> --output=<path> --temp=<temp path>
Options
--jdk-home=<path>Path to the JDK for which the shared index is being generated.
--output=<path>Output location for the generated shared indexes.
--temp=<temp path>(Optional) Temporary directory to use during the generation of the indexes.
Example
idea.bat dump-shared-index jdk --jdk-home=C:\Program Files\Java\jdk-14.jdk\Contents\Home --output=C:\Users\User\AppData\Local\JetBrains\IntelliJIdea2020.2\jdk-shared-indexes

By default, IntelliJ IDEA does not provide a command-line launcher. For information about creating a launcher script for IntelliJ IDEA, see Command-line interface.

Syntax
idea dump-shared-index jdk <options>
Options
--jdk-home=<path>Path to the JDK for which the shared index is being generated.
--output=<path>Output location for the generated shared indexes.
--temp=<temp path>(Optional) Temporary directory to use during the generation of the indexes.
--use-xz-compression=true|false(Optional; true by default) Compress shared index output with xz algorithm.
Example
idea dump-shared-index jdk --jdk-home=/Library/Java/JavaVirtualMachines/jdk-14.jdk/Contents/Home --output=/Users/User/Library/Caches/JetBrains/IntelliJIdea2020.2/jdk-shared-indexes

You can find the script for running IntelliJ IDEA in the installation directory under bin. To use this script as the command-line launcher, add it to your system PATH as described in Command-line interface.

Syntax
idea.sh dump-shared-index jdk <options>
Options
--jdk-home=<path>Path to the JDK for which the shared index is being generated.
--output=<path>Output location for the generated shared indexes.
--temp=<temp path>(Optional) Temporary directory to use during the generation of the indexes.
--use-xz-compression=true|false(Optional; true by default) Compress shared index output with xz algorithm.
Example
idea.sh dump-shared-index jdk --jdk-home=/usr/jdk/jdk-14.jdk/Contents/Home --output=~/.cache/JetBrains/IntelliJIdea2020.2/jdk-shared-indexes

Shared project indexes

Shared project indexes are built for all project sources, libraries, and SDKs. You can generate them on one computer and safely apply on another computer. This is the main advantage that shared indexes offer over ordinary indexes.

Shared indexes generated by a source IDE build may or may not be applicable to the target IDE build. It depends on whether versions of individual indexers in the source IDE match versions of the same indexers in the target IDE:

  • Different OSs: not applied

    Currently, shared project indexes are OS-specific.

  • Different format versions: not applied

    The format of an index depends on the implementation of internal data structures, which may differ between IDE builds.

  • Versions of some indexers don’t match: partially applied

    Only the matching shared indexes are applied. Non-matching indexes will be built locally.

  • Versions of all indexers match: fully applied

    All shared indexes are applied. Only files not related to the shared index will be built locally.

Share project indexes from the command line

To be able to export and share project indexes, the upload-local tool must be installed.

Install the upload-local tool

  1. Download the upload-local/<version>/upload-local-<version>.zip artifact from Bintray. We recommend that you get the latest version of the tool.

  2. Extract the contents of the .zip file and run the OS-specific startup script located in the bin directory.

Prepare the IDE for sharing project indexes

  1. Create the following directories or remove the contents from the existing ones:

    • <temp>/ide-system
    • <temp>/ide-config
    • <temp>/ide-log

    Note that in different operating systems, the temp directory has a different location.

  2. Copy the <IDE home>/bin/idea.properties file to the <temp> directory.

    Rename idea.properties to ide.properties in <temp>.

  3. Change the following properties in the <temp>/ide.properties file:

    • idea.system.path=<temp>/ide-system
    • idea.config.path=<temp>/ide-config
    • idea.log.path=<temp>/ide-log

    If you don't have these properties in the file, add them at the end.

  4. Set a temporary environment variable to specify the custom IDE properties file. To do so, run the following command:

    set IDEA_PROPERTIES=<temp>\ide.properties
    export IDEA_PROPERTIES=<temp>/ide.properties

Export project indexes

  1. Make sure that the <temp>/generate-output directory is empty. If there's no such a directory, do not create it as this will be done automatically during index export.

  2. Run the IDE with the following command line to export project indexes to the <temp>/generate-output.

    <IDE command-line launcher> dump-shared-index project --output=<temp>/generate-output --tmp=<temp>/temp --project-dir=<path> --project-id=<project-name> --commit=<Git HEAD>

You can find the script for running IntelliJ IDEA in the installation directory under bin. To use this script as the command-line launcher, add it to your system PATH as described in Command-line interface.

Syntax
idea.bat dump-shared-index project --output=<temp>/generate-output --tmp=<temp>/temp --project-dir=<path> --project-id=<project-name> --commit=<Git HEAD>
Options
--output=<temp>/generate-outputOutput location for the generated shared indexes in the <temp> folder.
--tmp=<temp>/tempThe temp directory used for the internal needs of the IDE.
--project-dir=<path>The path to the project for which you want to export indexes.
--project-id=<id>The name of the project.
--commit=<vcs revision>

The VCS revision identifier (for example, Git commit hash) representing the state of the project for which the shared index is being generated.

This is needed to lay out the shared indexes of several VCS revisions in the file storage.

This identifier is optional. If it is not specified, it will be set to -.

By default, IntelliJ IDEA does not provide a command-line launcher. For information about creating a launcher script for IntelliJ IDEA, see Command-line interface.

Syntax
idea dump-shared-index project --output=<temp>/generate-output --tmp=<temp>/temp --project-dir=<path> --project-id=<project-name> --commit=<Git HEAD>
Options
--output=<temp>/generate-outputOutput location for the generated shared indexes in the <temp> folder.
--tmp=<temp>/tempThe temp directory used for the internal needs of the IDE.
--project-dir=<path>The path to the project for which you want to export indexes.
--project-id=<id>The name of the project.
--commit=<vcs revision>

The VCS revision identifier (for example, Git commit hash) representing the state of the project for which the shared index is being generated.

This is needed to lay out the shared indexes of several VCS revisions in the file storage.

This identifier is optional. If it is not specified, it will be set to -.

You can find the script for running IntelliJ IDEA in the installation directory under bin. To use this script as the command-line launcher, add it to your system PATH as described in Command-line interface.

Syntax
idea.sh dump-shared-index project --output=<temp>/generate-output --tmp=<temp>/temp --project-dir=<project> --project-id=<project-name> --commit=<Git HEAD>
Options
--output=<temp>/generate-outputOutput location for the generated shared indexes in the <temp> folder.
--tmp=<temp>/tempThe temp directory used for the internal needs of the IDE.
--project-dir=<path>The path to the project for which you want to export indexes.
--project-id=<id>The name of the project.
--commit=<vcs revision>

The VCS revision identifier (for example, Git commit hash) representing the state of the project for which the shared index is being generated.

This is needed to lay out the shared indexes of several VCS revisions in the file storage.

This identifier is optional. If it is not specified, it will be set to -.

The following files are exported to <temp>/generate-output:

  • shared-index-project-<name>-<hash>.ijx.xz
  • shared-index-project-<name>-<hash>.metadata.json
  • shared-index-project-<name>-<hash>.sha256

Move generated files to the storage

  1. Download all the contents of your file storage to <temp>/indexes, or create this empty directory if the remote file storage is not configured yet.

  2. Copy the generated files (.ijx.xz, .metadata.json, .sha256) from <temp>/generate-output to a subdirectory of <temp>/generate-output.

    This can be any folder, for example <temp>/indexes/project/<project name>/<VCS hash>/<indexes>.

Generate metadata

  • Generate auxiliary files used by the IDE to look up for and download shared indexes. To do so, run the upload-local tool with the following command line.

    <upload-local tool> --indexes-dir=<temp>/indexes --url=<file storage root UR>
Options
<upload-local tool>The path to the upload-local tool startup script located in bin in the tool directory.
--indexes-dir=<dir>

The directory containing all the files available in the file storage, as well as the newly generated shared indexes residing in a suitable location beneath this directory.

The tool will generate the missing files needed for IDE lookup and replace existing ones, if necessary. After the tool has finished running, all the contents of this directory must be uploaded to the file storage. This will set the new state of the storage.

--url=<file storage root URL> The base URL of the file storage root directory. The upload-local tool will substitute the download URL in all the corresponding .json index lists.
Example
/Users/User/Desktop/upload-local-1.0.3/bin/upload-local --indexes-dir=/var/folders/dr/xxx_x00x0x0_x0xx000xx000000xx/T/indexes --url=https://my-file-storage.com/intellij-indexes

Upload the index files

  1. Upload all the files from <temp>/indexes to the file storage as is.

    If there are already uploaded index files in the storage, update them.

  2. In the project directory, create a new file intellij.yaml and add the following code to this file:

    sharedIndex: project: - url: <feed URL>

    Replace <feed URL> with the URL of your file storage in the following format: <file storage root URL>/project/<project-id>.

Configure index update

Once the project indexes are uploaded to the file storage, they can be downloaded and applied on another computer.

  1. In the project directory, create a new file intellij.yaml and add the following code to this file:

    sharedIndex: project: - url: <feed URL>

    Replace <feed URL> with the URL of your file storage in the following format: <file storage root URL>/project/<project-id>.

  2. In the Settings/Preferences dialog Ctrl+Alt+S, select Tools | Shared Indexes.

  3. From the Project indexes list, select how you want to download shared indexes from the storage.

    Select Download automatically to silently download indexes whenever they are needed or select Ask before download if you want to manually allow every download.

    Configuring options for downloading shared indexes
  4. Apply the changes and close the dialog.

Project indexes will be downloaded to the index/shared_indexes in the IDE system directory.

Share project indexes manually

This method of sharing indexes is experimental. We recommend using a file storage for sharing indexes.

Configure a folder for shared indexes

  1. Create an empty folder on your computer that you will be using as an index storage.

    The recommended location for project indexes is the IDE system directory. Do not place shared indexes under a VCS.

  2. In IntelliJ IDEA, select Help | Edit Custom VM Options from the main menu.

  3. In the file that opens, add the following line: -Don.disk.shared.index.root=shared-index-root. Replace shared-index-root with the folder that you use as an index storage.

    Example: -Don.disk.shared.index.root=/Users/user/Library/Caches/JetBrains/IntelliJIdea2020.2/shared-indexes

  4. Restart the IDE to apply the changes.

Export project indexes

  1. Press Ctrl+Shift+A, type Dump Project Shared Index, and click the action once you locate it in the list.

    Exporting shared indexes for a project

  2. In the dialog that opens, select an empty folder in which you want to export shared project indexes, and click Open.

  3. In the notification that opens, click Yes to compress the output files.

    Notification prompting you to compress indexes

  4. In the next dialog, leave the input field blank and click OK.

IntelliJ IDEA exports three files: a file with the exported indexes, a file with metadata, and a digest file. The process might take a few seconds.

After that, each time IntelliJ IDEA needs to re-index your project, it will be using your shared project indexes. If some indexes are missing, the IDE will build them locally.

Distribute project indexes manually

You can transfer shared indexes to another computer manually. In this case, you need to configure the folders for shared indexes using custom VM options on both computers beforehand.

  1. Export indexes for the necessary project.

  2. Place the file with the .ijx extension to the pre-configured index folder on another computer.

Remove downloaded shared indexes

If you don't need project indexes anymore (for example, if the project is no longer developed), you can remove them all together. In this case, the IDE will remove the regular indexes and all downloaded shared indexes for the project and for the project JDK.

  1. From the main menu, select File | Invalidate Caches / Restart.

  2. In the dialog that opens, select Invalidate and Restart.

Last modified: 30 July 2020