A Gradle build can have one or more projects. Projects are listed in a flat list with the root project listed first, and sub-projects listed alphabetically thereafter.

When you expand a project, tasks are listed in a tree, grouped by the task group. You can toggle the display of the tasks by clicking on the Show Flat List/Show Tree button in the tree view header.

The project's dependencies are included in the Dependencies item under the project. The dependencies are grouped by Gradle configurations and you can expand each configuration to find the corresponding ones. For omitted dependency (marked with a (*)), you can use the inline button Go to Omitted Dependency to go to the previously listed dependency.

Tasks can be run via:

• Gradle Projects or Recent Tasks tree views
• Run Task command
• Run a Gradle Build command

A running task will be shown with an animated "spinner" icon in the tree views, along with Cancel Task & Restart Task buttons. The Cancel Task button will gracefully cancel the task. The Restart Task button will first cancel the task, then restart it.

A task will be run a vscode terminal where you can view the task output.

Send a SIGINT signal (ctrl/cmd + c) in the terminal to gracefully cancel it.

Tasks run via the Run a Gradle Build command are not reflected in any of the tree views. Use this command to specify your own Gradle build arguments, for example to run multiple tasks or to exclude tasks.

Use one terminal for each task type (default):

"gradle.reuseTerminals": "task"

Use one terminal for all tasks:

"gradle.reuseTerminals": "all"

Don't re-use terminals for any tasks. A new terminal will be created for each task run:

"gradle.reuseTerminals": "off"

This extension provides an experimental feature to debug JavaExec and Test tasks. Before using this feature you need to install the Debugger for Java and Language Support for Java extensions.

You might need to specify whether you want to clean output cache before debugging, to ensure Gradle doesn't skip any tasks due to output caching (this is most useful when debugging tests).

Output cache is cleaned by adding a cleanTaskName task (eg cleanTest) to the build.

You should now see a debug command next to the run command in the Gradle Projects view. The debug command will start the Gradle task with jdwp jvmArgs and start the vscode Java debugger.

As there could be many tasks in a Gradle project, it can be useful to pin commonly used tasks. Pinned tasks will be shown under their project item. Pin a task by accessing the task context menu (by right-clicking a task). You can also pin a task with specific arguments.

To unpin a task, access the task context menu and select Unpin Task, or unpin all pinned tasks by clicking on the Unpin all Tasks button in the overflow button of tree view header.

Recently run Gradle tasks are listed in a separate tree view. This can be useful to see a history of tasks and to easily access the associated task terminals.

The number shown next to the task is the amount of times the task has been run. Click on the Show Terminal button next to a task to view the most recent terminal for that task. Click on the Close Terminal/s button to close the terminal/s for that task.

Click on the Clear Recent Tasks button in the tree view header to remove all recent tasks from the list, or click on the Close All Terminals button to close all task terminals.

Gradle daemon processes are listed by their process ID in a separate tree view and can have the following states: IDLE, BUSY, STOPPED, STOPPING, CANCELED.

Stop individual daemons by clicking on the Stop Daemon button next to the listed daemon.

Stop all daemons by clicking on the Stop Daemons button in the tree view header.

After stopping a daemon, it will remain in the STOPPED state for a while, but the underlying process won't exist. This is the default Gradle behaviour.

Most of the time there should be no reason to stop a daemon. View more info on the Gradle Daemon from the Gradle website.

The extension uses the Gradle wrapper to list daemons, and is quite a slow process. If the daemon view is not useful for you, you can simply collapse the view, or disable it completely.

When opening a Groovy Gradle file, the Gradle language server will start and provide language features for you.

Basically, we offer a basic groovy syntax highlighting in gradle files, as VS Code does by default. After language server started, it will analyze the Gradle file and provide semantic tokens information, providing more precise highlighting results.

The Gradle language server will provide the document outline for the current Gradle file. This view will help you to navigate to any part of this Gradle file easily.

The Gradle language server will use Groovy compile engine to analyze the Gradle build file and report syntax errors if exist. It will also get script classpaths from Gradle Build so that it can report compilation errors. The Gradle default imports are supported.

The Gradle language server supports basic auto completions for a Gradle file, including

• Basic Gradle closures (e.g. dependencies {})
• Gradle closures from plugins (e.g. java {})
• Available methods in Gradle closures (e.g. mavenCentral() in dependencies {})
• Available fields in Gradle closures (e.g. sourceCompatibility in java {})
• Available dependencies in Maven central when declaring a dependency in dependencies closure
• Basic auto completion for settings.gradle (e.g. include())

• List Gradle Tasks & Projects
• Run Gradle tasks as VS Code tasks
• View Gradle Dependencies
• Supports massive Gradle projects (eg with 10000+ tasks)
• Uses the Gradle Tooling API to discover and run Gradle tasks
• Uses a long running gRPC server which provides good performance
• Supports Kotlin & Groovy build files
• Supports multi-project builds
• Supports multi-root workspaces
• Supports nested projects (enabled via setting)
• Show flat or nested tasks in the explorer
• Gracefully cancel a running task
• Debug tasks
• Run/debug a task with arguments (supports both build & task args, eg gradle tasks --all --info)
• Pin tasks
• List recent tasks
• List & stop daemons
• Reports Gradle dist download progress
• Supports syntax highlighting for Groovy Gradle files
• Supports document outline for Groovy Gradle files
• Supports error reporting for Groovy Gradle files
• Supports auto completion for Groovy Gradle files

The integrated terminal has a limited buffer size and will not show the full output for tasks that generate a large output. Increase the terminal buffer size in your settings, for example:

{
  "terminal.integrated.scrollback": 5000
}

This error means the Gradle Task server has stopped, or there was an error starting it. Click on "Restart Server" to restart it.

If you continue to get this error, view the task error messages by selecting "Gradle Tasks" in the output panel.

The task server is started using a shell script generated by CreateStartScripts. The script uses #!/usr/bin/env sh and is as portable as the Gradle wrapper script. If there are any problems executing the start script then it's likely an issue either with your PATH, or Java is not installed.

PATH problems

The following error demonstrates a typical issue with your PATH:

env: sh: No such file or directory
The terminal process terminated with exit code: 127

Use the following task to debug your shell environment within vscode:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Print task shell info",
      "type": "shell",
      "command": "echo \"Path: $PATH \nShell: $SHELL\"",
      "problemMatcher": []
    }
  ]
}

Fixing your $PATH

Check your dotfiles (eg ~/.bash_profile, ~/.bashrc, ~/.zshrc) and fix any broken PATH exports. See Issues with environment vars below for more information.

Java path problems

You might see an error like:

ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.

The start script should find the path to Java in the usual locations. If you get this error it suggests an issues with your $PATH or you simply haven't installed Java. Run the Gradle wrapper script (eg ./gradlew tasks) to debug further, or see Issues with environment vars below for more information.

Shell environment

Another potential problem is that the PATH or JAVA_HOME environment vars have been defined within .bashrc. See Issues with environment vars below for more information.

(The following is only relevant for MacOS & Linux.)

The Gradle Server is launched inside a non-interactive non-login shell, which loads the profile script (not the rc script). This means the shell will not load, for example, ~/.bashrc. If you've defined PATH or other environment variables within ~/.bashrc, they will not be available for the server startup script and not be available to Gradle.

Generally, environment settings should be defined in in ~/.bash_profile, but as a workaround, you can load ~/.bashrc from within ~/.bash_profilefor example:

if [ -r ~/.bashrc ]; then
  source ~/.bashrc
fi

You might notice some Java processes are not closed after existing VS Code. These processes are the Gradle Daemons that Gradle spawns. This is the default behaviour of Gradle.

You'll have N processes per Gradle version. Eventually Gradle will shut them down. Read more about the Gradle Daemon.

This extension is incompatible with the following extensions:

• spmeesseman.vscode-taskexplorer

The reason for the incompatibility is due to the extensions providing the same tasks types (gradle) with different task definitions.