# Tutorial: Remote debug

In this tutorial, we'll learn how to attach to a local or remote process using the IntelliJ IDEA debugger. It walks through a basic remote debugging scenario to get you started.

> **Tip:**
> If you're looking for complete explanations of remote debug settings and features, refer to [Attach to process](attach-to-process.html).

## Overview

Remote debugging lets you control and inspect a Java program running on another machine as if it were local.

To do this, you first start the application on the remote computer and configure it to accept debugger connections by adding a special VM option. This option makes the remote JVM wait for incoming connections from a debugger.

Once the remote app is up and listening, you use your local machine to start a debugger in “attach” mode. This connects the IntelliJ IDEA's debugger to the remote application over the network, allowing you to debug it.

> **Note:**
> For simplicity, we will launch the debugger and the host application on the same computer. The steps, however, are identical for debugging that is actually remote, so you will be able to use the same procedure for both scenarios.

## Create a project

First, let's set up the project that we'll be debugging – a simple program that outputs the capital letters from `A` to `Z`.

> **Tip:**
> You can use your own project instead of the one created in this chapter. If you do, make sure that:
>
>
>
> * the app is compiled with debug information. This is the default compiler setting and must not be overridden. Otherwise, most of the debugger functionality will be unavailable.
>
> * you have the source code of the application. While it is possible to use decompiled code for debugging, it is more complicated and not covered in this tutorial.

Procedure:

1. [Create a new project](creating-and-running-your-first-java-application.html#create-project).

2. Create a class named `Alphabet`.

![Alphabet.java in the Project tool window](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_project_1.png)

3. In the body of the `Alphabet` class, paste the following definition of the `main` method:

```JAVA
public static void main(String[] args) {
    System.out.println("Starting");
    for (char c = 'A'; c < 'Z'; c++) {
        try {
            Thread.sleep(2500);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        System.out.println(c);
    }
    System.out.println("Complete");
}
```

## Create run configurations

To allow the debugger to attach, we need to run the application with special parameters (more on them shortly). In this tutorial, we'll set up a run/debug configuration that will do this for us. This way, we are going to have two run/debug configurations: [one for running the app](#host_rc) and [another for attaching to it](#debugger_rc).

### Set up the debugger

First, we need to set up the run/debug configuration that will be used for attaching to the host application.

Procedure:

1. In the main menu, go to `Run | Edit Configurations` or press `Alt+Shift+F10` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Alt+Shift+F10` (NetBeans), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS)) then `0` (Windows), `0` (macOS), `0` (IntelliJ IDEA Classic (macOS)), `0` (macOS System Shortcuts), `0` (XWin), `0` (GNOME), `0` (KDE), `0` (Emacs), `0` (Sublime Text), `0` (Sublime Text (macOS)), `0` (NetBeans), `0` (Visual Studio), `0` (Visual Studio (macOS)), `0` (Eclipse), `0` (Eclipse (macOS)).

2. In the Run/Debug Configurations dialog, click the Add New Configuration button ![](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app.expui.general.add.svg) and select Remote JVM Debug.

![The Add New Configuration button in the top-left corner of the Run/Debug Configurations dialog](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_rc_1.png)

3. Configure/use the following properties:

* Name: define a convenient name for this run/debug configuration or keep the default value.

* Host: the address of the machine where the host app will run. Since we are running it on the same machine, it needs to be `localhost`. If the program was running on another machine, we would specify its address here, for example: `192.168.17.43`. > **Note:** > The default port (5005) does not have to be changed. However, make sure that it is not in use and not blocked by a firewall.

* Command line arguments for remote JVM: the VM options that the host application needs to be started with. We will use them in the other run/debug configuration. You can copy them now or get back to this field later.

![The Name, Host, and Command line arguments for remote JVM fields](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_rc_2.png)

4. Click Apply.

### Set up the host app

There are no restrictions on how exactly the host application needs to be run. For example, you can [package the app as a JAR](compiling-applications.html#package_into_jar) and run it using the following command line:

```SHELL
java -jar -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 remote-debug.jar
```

> **Note:**
> For the purposes of debugging, there is no difference how we run the application as long as it gets the VM options that start the program with the debug agent.

In this tutorial, we are going to use a run/debug configuration that will do most of the work for us.

Procedure:

1. Right-click anywhere in the body of the `Alphabet` class. Select More Run/Debug, then Modify Run Configuration.

2. Click Modify options, then select Add VM options. In the VM options field, paste the options that you copied from the [debug configuration](#debugger_rc).

![VM options field in the run/debug configuration of the host app](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_rc_3.png)

3. Click Apply.

## Run the app

Now that we prepared all that is necessary, we can proceed with running our application.

Procedure:

* Press `Alt+Shift+F10` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Alt+Shift+F10` (NetBeans), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS)) and select `Alphabet`.

![The Run popup](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_run_1.png)

In the program output, the first line will be:

```SHELL
Listening for transport dt_socket at address: 5005
```

This indicates that we have enabled the debug agent and our program is ready to accept incoming debugger connections.

If the line doesn't appear, ensure the port is not being used by another application or blocked by a firewall or security settings.

## Attach to process

Procedure:

1. Click the gutter at line 10 to set a line breakpoint there.

![Setting a line breakpoint at line 10](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_run_2.png)

2. Press `Alt+Shift+F9` (Windows), `⌃ ⌥ D` (macOS), `⌥ ⇧ F9` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ D` (macOS System Shortcuts), `Alt+Shift+F9` (XWin), `Alt+Shift+F9` (GNOME), `Alt+Shift+F9` (KDE), `Alt+Shift+F9` (Emacs), `Alt+Shift+F9` (Sublime Text), `⌃ ⌥ D` (Sublime Text (macOS)), `Alt+Shift+F9` (NetBeans), `Alt+Shift+F9` (Visual Studio), `⌃ ⌥ D` (Visual Studio (macOS)), `Alt+Shift+F9` (Eclipse), `⌃ ⌥ D` (Eclipse (macOS)) and select your remote debug configuration.

![The Debug popup](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_run_3.png)

As the result, the program is suspended at the breakpoint, and you can perform any debugging actions like [stepping](stepping-through-the-program.html), [expression evaluation](examining-suspended-program.html#evaluating-expressions), and so on.

![The blue highlighting indicates that the program is suspended at line 10](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_run_4.png)

The debugging process is the same regardless of how and where your app is launched. After you have connected, you can use the same debugger features as if you were launching your app right from IntelliJ IDEA.

## Close the debug session

Procedure:

1. Close the corresponding session tab in the Debug tool window.

![The current session tab in the top part of the Debug tool window](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_disconnect_0.png)

2. Select if you want to terminate the process or disconnect from it.

* Disconnect stops the debug session while the process continues to run

* Terminate stops both the process and the debug session

![The popup is asking whether you want to only stop the session (Disconnect)
or both the session and the process (Terminate)](https://resources.jetbrains.com.cn/help/img/idea/2026.2/debug_remote_tutorial_disconnect_1.png)

> **Tip:**
> If you only want to disconnect the debugger without terminating the process, click Stop ![the Stop button](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app.expui.run.stop.svg) on the debugger's toolbar.