A run configuration is a specific type of run profile. Run configurations can be managed from the UI and are persisted between IDE restarts. They allow users to specify execution options like a working directory, environment variables, program arguments, and other parameters required to run a process. Run configurations can be started from the Run toolbar, the editor, and executed programmatically from actions or other components.
The following diagram shows the key run configurations classes:
Run Configuration API (except
SettingsEditor class, which is a class shared by many IntelliJ Platform APIs) is a part of the Execution API.
The entry point of a run configuration implementation is
ConfigurationType. It is responsible for the run configuration type and instances presentation and contains configuration factories. A single configuration type can have multiple configuration factories, e.g., the Docker configuration type can create run configurations for:
To see the list of configuration types available in the IDE, go to Add button (+ icon).and click the
ConfigurationType implementations are registered in the
com.intellij.configurationType extension point (EP).
Standard base classes for configuration type implementations are:
SimpleConfigurationType- used for configuration types that have a single configuration factory. Actually, this configuration type is also a configuration factory, and there is no need for setting up a factory.
ConfigurationTypeBase- used for configuration types that have multiple configuration factories. Factories should be added in the constructor by calling the
Sometimes, it is required to provide run configurations programmatically from contexts external to run configuration UI. Implementing
VirtualConfigurationType blocks the possibility of adding and removing run configurations of this type in the Run/Debug Configurations panel. Editing its template is also not available.
ConfigurationFactory classes are responsible for creating run configuration instances. The only method required to be implemented is
createTemplateConfiguration(), which is called once for each project to create the run configuration template. The actual run configurations are created in the
createConfiguration() method by cloning the template.
Configuration factory presentation is inherited from the containing configuration type. If customization is needed, override the presentation methods in the factory class.
By default, configurations created by a given factory are not editable in Dumb Mode. To enable editing them in Dumb Mode, return
When implementing a run configuration class, consider using one of the standard base classes:
RunConfigurationBase- a general-purpose base class that contains the most basic implementation of a run configuration.
A run configuration may allow editing its general settings and settings specific to a program runner. If it is required, a
RunConfiguration implementation should return a
SettingsEditor instance from:
getConfigurationEditor()for editing run configuration settings
getRunnerSettingsEditor()for editing settings for a specific program runner
SettingsEditor implementation must provide the following methods:
getComponent()- creates a UI component for displaying settings controls
applyEditorTo()- copies the current editor UI state into the target settings object
resetEditorFrom()- resets the current editor UI state to the initial settings state
In the case of run configuration settings, the settings object is
RunConfiguration itself. Settings specific to a program runner must implement
If the settings editor requires validation, implement
If the settings editor is complex, see Simplifying Settings Editors for solutions.
Example: DemoSettingsEditor from the
run_configuration code sample.
Run configuration settings are persistent. They are stored in the file system and loaded back after the IDE restart. Persisting and loading settings are performed by
readExternal() methods of
RunConfiguration class correspondingly.
The actually stored configurations are represented by instances of the
RunnerAndConfigurationSettings class, which combines a run configuration with runner-specific settings and stores general run configuration flags and properties.
Creating a Run Configuration Programmatically
If a plugin requires creating run configurations programmatically, .e.g, from a custom action, perform the following steps:
RunManager.createConfiguration()- creates an instance of
RunManager.addConfiguration()- makes the created configuration persistent by adding it to either the list of shared configurations stored in a project or to the list of local configurations stored in the workspace file.
Creating a Run Configuration from Context
Run configurations can be created and run from context, e.g., by right-clicking an application main method, a test class/method, etc., directly in the editor or the project view. This is achieved by implementing
LazyRunConfigurationProducer and registering it in
The extension requires implementing the following methods:
getConfigurationFactory()- returns the factory creating run configurations of the type specified in the extension class implementation.
setupConfigurationFromContext()- receives a blank configuration of the specified type and a
ConfigurationContextcontaining information about a source code location (accessible by calling
getPsiLocation()). The implementation needs to check whether the location is applicable to the configuration type (e.g., if it is in a file of the supported language). If it is, put the correct context-specific settings into the run configuration and return
isConfigurationFromContext()- checks if a configuration was created from the specified context. This method allows reusing an existing run configuration, which applies to the current context, instead of creating a new one and possibly ignoring the user's customizations in the existing one.
If the run configuration requires additional data before it is executed for the first time, override
RunConfigurationProducer.onFirstRun() to provide it or display UI to get the data from the user.
To support the automatic naming of configurations created from context, the configuration should extend
LocatableConfigurationBase. It supports generating a name for a configuration from its settings and tracking whether the user changed the name.
Running Configurations from the Gutter
If a run configuration is closely related to a PSI element (e.g., runnable method, test, etc.), it is possible to allow running configurations by clicking the editor gutter icon. It is achieved by implementing
RunLineMarkerContributor, which provides information like the icon, tooltip content, and available actions for a given PSI element.
The standard method for providing the information is
getInfo(). If computing the information is slow, implement
getSlowInfo(), which is used by the editor highlighting mechanism to gather information in batch, and apply all the information at once to avoid icons blinking.
To provide the standard executor actions like Run, Debug, etc., use
Starting a Run Configuration Programmatically
The easiest way to run an existing run configuration is using
RunnerAndConfigurationSettings can be retrieved with, e.g.,
RunManager.getConfigurationSettings(ConfigurationType). The executor can be retrieved with a static method if a required executor exposes one or with
Validating a Run Configuration
To check, whether a run configuration is configured correctly and can be executed, implement the
RunConfiguration.checkConfiguration(). In case the run configuration settings are incomplete, the method should throw one of the following exceptions:
RuntimeConfigurationWarning- in case of a problem, which doesn't affect execution
RuntimeConfigurationException- in case of non-fatal error, which allows executing the configuration
RuntimeConfigurationError- in case of fatal error that makes it impossible to execute the run configuration
If the configuration contains any warnings or errors, its icon will be patched with the error indicator and the message will be displayed in the configuration settings page. In case of
RuntimeConfigurationError, if a user tries to execute the configuration, the run configuration settings dialog will be presented, so that the user can fix the issues before the execution.
All the mentioned exceptions allow providing a quick fix for the reported issue. If the quick fix implementation is provided, the quick fix button will be displayed next to the error message.
Simplifying Settings Editors
If a run configuration settings editor is complex, consider implementing one of the following solutions to simplify the UI:
Fragmented Settings Editor
Fragmented Settings allow for the creation of a cleaner run configuration settings editor. The fragmented editor is built of reusable fragments, which can be shared between different run configuration editors.
When a user creates a new run configuration from a template, only essential fragments are displayed at first. More advanced options are hidden and must be explicitly enabled by the user from the Modify options dropdown. It makes the editor smaller, freeing it from the clutter of unused settings fields.
To implement a fragmented settings editor in a run configuration, extend
RunConfigurationFragmentedEditor and implement
createRunFragments(). The method must return a list of
SettingsEditorFragment instances, which represent particular settings fragments that users can enable and configure.
Settings Editor Groups
A complex settings editor can be split into smaller editors focused on a specific area, e.g.:
Configuration - containing the main configuration settings
Logs - containing settings related to logging
Coverage - containing settings related to code coverage
These editors should be added to the
SettingsEditorGroup object, which is a
SettingsEditor's implementation itself and must be returned from
getRunnerSettingsEditor(). Each editor added to the group is displayed in a separate tab.
Some run configurations contain references to classes, files, or directories in their settings, and these settings usually need to be updated when the corresponding element is renamed or moved. To support that, a run configuration needs to implement the
RefactoringListenerProvider.getRefactoringElementListener()'s implementation should check whether the refactored element is referred from the run configuration. If it is, return a
RefactoringElementListener that updates the run configuration according to the new name and location of the element.
Modifying Existing Run Configurations
Plugins can modify existing run configurations before they are run, e.g., by adding additional process parameters. However, there is no single platform-wide extension point, and different IDEs provide different configuration base classes and extension points, allowing for their modifications. To see what is possible in your case, check the
RunConfigurationExtensionBase inheritors. Examples:
Referencing Environment Variables in Run Configurations
Run configurations can define user environment variables specific to a given run configuration and include system environment variables. Sometimes, it is convenient to reference existing variables in newly created variables, e.g., if a user creates an
EXTENDED_PATH variable and builds it from a custom entry and the system
PATH variable, they should reference it in the value by surrounding it with the
To substitute variable references with the actual references, it is required to call
EnvironmentUtil.inlineParentOccurrences() (available since 2023.2).
Before Run Tasks
Sometimes, it is necessary to perform specific tasks before a configuration is actually run, e.g., build the project, run a build tool preparation task, launch a web browser, etc. Plugins can provide custom tasks that can be added by users to a created run configuration.
To provide a custom task, implement
BeforeRunTaskProvider and register it in
com.intellij.stepsBeforeRunProvider EP. The provider implementation is responsible for creating a task instance for a given run configuration and executing the task.
Macros are dynamic variables, which can be referenced in run configurations, and expanded to actual values when a run configuration is executed.
For example, a macro with a name
ProjectFileDir can be referenced as
$ProjectFileDir$ in a run configuration command line argument. It is expanded to the absolute path of the current project directory when the run configuration is executed by a user.
A list of built-in macros is available in the IntelliJ IDEA Web Help and other products' documentation pages.
Adding Macro Selector in Run Configuration Editor
Macro selecting support can be added to a text field on the run configuration editor by installing it with
MacrosDialog.addMacroSupport() or other similar methods from this class. After installation, a text field will be extended by a button invoking the macro dialog, which lists available macros with descriptions and previews. After selecting and accepting a macro from the list, the macro placeholder is inserted into the text field at the current caret position.
Expanding Macros Before Execution
Macros used in run configuration must be expanded to actual values before the process execution. It is usually done in the
RunProfile.getState() method called during the execution workflow. To expand configured values, use one of
ProgramParametersConfigurator 's method:
expandMacrosAndParseParameters(). See their Javadocs for the details.
Providing Custom Macros
If the predefined list of macros is insufficient, a plugin can provide custom macros by extending
Macro and registering it in the