# Attach to running Go processes with the debugger

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/help/go/2026.3/llms.txt).

In GoLand, you can attach the debugger to a running Go process [on a local machine](#attach-to-a-process-on-a-local-machine), [on a remote machine](#attach-to-a-process-on-a-remote-machine), or [in the Docker container](#attach-to-a-process-in-the-docker-container).

## Attach to a process on a local machine

You can debug an application that you launched from the command line. In this case, the application runs outside the IDE but on the same local machine. To debug the application, you need to open the project in the IDE and attach the debugger to the running process.

You can use the [example Go application on GitHub](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/main.go) to follow these steps.

Procedure: Step 1. Install the gops package

* Open the Terminal tool window (`View | Tool Windows | Terminal`) and run the following command:

```CONSOLE
go install github.com/google/gops@latest
```

* Click `Run | Attach to Process` (`Ctrl+Alt+F5` (Windows), `⌥ ⇧ F5` (macOS), `⌥ ⇧ F5` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ F5` (macOS System Shortcuts), `Ctrl+Alt+5` (XWin), `Ctrl+Alt+5` (GNOME), `Ctrl+Alt+5` (KDE), `Ctrl+Alt+F5` (Emacs), `Ctrl+Alt+F5` (Sublime Text), `⌥ ⇧ F5` (Sublime Text (macOS)), `Ctrl+Alt+F5` (VSCode), `⌥ ⇧ F5` (VSCode (macOS))). In the notification window, click the Invoke 'go get gops' link.

Procedure: Step 2. Build and run the application

1. Open the Terminal tool window (`View | Tool Windows | Terminal`) and build the application with compiler optimizations and inlining disabled:

macOS and Linux:

```BASH
go build -gcflags="all=-N -l" -o myApp
```

Windows:

```POWERSHELL
go build -gcflags="all=-N -l" -o myApp.exe
```

2. Run the compiled executable.

macOS and Linux:

```BASH
./myApp
```

Windows:

```POWERSHELL
.\myApp.exe
```

> **Note:**
> Do not use `-ldflags="all=-w"` or `-ldflags="-w"` flags. These flags are incompatible with debugging the application because they strip out the necessary DWARF information that is required by Delve.

> **Note:**
> Symbolic links in source paths can prevent the debugger from locating files or setting breakpoints. If this happens, try opening and building the project from the resolved directory rather than its symbolic link. For background information, refer to the [Delve source-path troubleshooting guide](https://github.com/go-delve/delve/blob/master/Documentation/faq.md#substpath).

Procedure: Step 3. Attach to and debug the running process

1. Click the gutter next to the line of code where you want to set the breakpoint. In [the provided example](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/main.go), place the breakpoint on the line 23 (`message := fmt.Sprintf("Hello %s!", r.UserAgent())`). Read more about breakpoints in [Breakpoints](using-breakpoints.html).

2. Click `Run | Attach to Process` or use the shortcut `Ctrl+Alt+F5` (Windows), `⌥ ⇧ F5` (macOS), `⌥ ⇧ F5` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ F5` (macOS System Shortcuts), `Ctrl+Alt+5` (XWin), `Ctrl+Alt+5` (GNOME), `Ctrl+Alt+5` (KDE), `Ctrl+Alt+F5` (Emacs), `Ctrl+Alt+F5` (Sublime Text), `⌥ ⇧ F5` (Sublime Text (macOS)), `Ctrl+Alt+F5` (VSCode), `⌥ ⇧ F5` (VSCode (macOS)).

3. In the Attach with Debugger To window, select your application process and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (VSCode), `⏎` (VSCode (macOS)).

4. Trigger the event associated with the breakpoint in your application. If using the provided code example, open the [http://localhost:8080/](http://localhost:8080/) link in a browser.

## Attach to a process on a remote machine

You can connect to Delve on a remote computer to debug a Go process running there. The following example uses a Linux remote computer and an SSH tunnel.

> **Warning:**
> Delve connections are not authenticated and allow code execution in the debugged process. Keep the debugger port private. Use an SSH tunnel or a VPN when connecting from another computer. Use this setup for development, not production. For more information, refer to the [Delve remote debugging guidance](https://github.com/go-delve/delve/blob/master/Documentation/faq.md#remote).

To install Delve, you can use the following command:

```BASH
go install github.com/go-delve/delve/cmd/dlv@latest
```

> **Note:**
> Use a Delve version that supports the Go version used to build your application, and install it for the remote computer's operating system and architecture. Delve checks the application's Go version and debug-information format when it starts.

Procedure: Step 1. Build the application on the remote computer

* In a terminal on the remote computer, open the application directory and run:

```BASH
go build -gcflags="all=-N -l" -o myApp
```

This command compiles the `myApp` executable and disables compiler optimizations and inlining.

Procedure: Step 2. Run Delve on the remote machine

* You have two options to launch the debugger on the host machine:

* Start the application with Delve. `myApp` is the executable built in [Step 1](#step-1-build-the-application-on-the-remote-computer). ```CONSOLE dlv --listen=127.0.0.1:2345 --headless=true --api-version=2 exec ./myApp ``` If you need to pass arguments to the binary as-is, add the double dash sign (`--`) to the previous command and then necessary options (for example, `-- --config=/path/to/config/file`).

* You run the process, and the debugger attaches to the running process. `<PID>` is the process identifier of your application on the remote computer. Use a tool such as `ps` on that computer to find it. ```CONSOLE dlv --listen=127.0.0.1:2345 --headless=true --api-version=2 attach <PID> ```

Procedure: Forward the debugger port

1. In a terminal on your local computer, start an SSH tunnel:

```BASH
ssh -N -L 2345:127.0.0.1:2345 user@remote-host
```

Replace `user` and `remote-host` with your SSH username and the remote computer's address. Keep the SSH connection open while debugging.

2. Connect GoLand to `127.0.0.1:2345` as described below. The tunnel forwards this connection to Delve on the remote computer.

Procedure: Step 3. Start the debugging process on your local computer

1. Open the code of your application and place a breakpoint. In [the provided code example](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/main.go), set the breakpoint on line 23 (`message := fmt.Sprintf("Hello %s!", r.UserAgent())`). Read more about breakpoints in [Breakpoints](using-breakpoints.html).

2. Click `Run | Edit Configurations`. Alternatively, click the list of run/debug configurations on the toolbar and select Edit Configurations.

3. In the Run/Debug Configurations dialog, click the Add button (![the Add button](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)) and select Go Remote.

4. In the Host field, type `127.0.0.1` to use the SSH tunnel.

5. In the Port field, type the debugger port that you configured on [Step 2](#step-2-run-delve-on-the-remote-machine) (for example, `2345`).

6. Click Debug.

7. Trigger the event at the breakpoint in your application. If you used [the provided code example](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/main.go), open the `http://<host_address>:8080/` link in a browser.

The video below shows the debugger workflow, but predates the SSH tunnel setup. Use the listener address and tunnel from the steps above. In the video, the dark-themed IDE is on the local computer, and the light-themed IDE is on the remote computer.

[Video](https://resources.jetbrains.com/help/img/idea/2026.3/go_start_the_debugging_process_on_your_local_computer.mp4)

## Attach to a process in the Docker container

You can attach the debugger to a Go process that runs inside a Docker container. For more information about Docker, refer to [Docker](docker.html).

The following steps use Docker on your local computer. Publish the debugger port on `127.0.0.1` so other computers cannot connect to it.

For example purposes, you can use [the following Dockerfile](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/Dockerfile) for [this Go application](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/main.go).

> **Note:**
> The example Dockerfile uses an older Go image and a build with optimizations enabled. Before building it, update the Go image to a version supported by the Delve version you install. Replace the application build command with:
>
>
>
>
> ```DOCKERFILE
> RUN go build -gcflags="all=-N -l" -o /debuggingTutorial/app .
> ```

Procedure: Step 1. Create a Dockerfile configuration

1. Click `Run | Edit Configurations`. Alternatively, click the list of run/debug configurations on the toolbar and select Edit Configurations.

2. In the Run/Debug Configurations dialog, click the Add button (![the Add button](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)) and select `Docker | Dockerfile`.

3. In the Dockerfile field, click the Browse icon (![the Browse icon](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.menu-open.svg)) and navigate to `Dockerfile` in the file browser. If you use the example from this section, navigate to [this Dockerfile](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/Dockerfile).

4. In the Container name field, type the container name (for example, `debugging-tutorial`).

5. In the Run/Debug Configurations dialog, click Modify and select Bind ports and Run options.

![Bind ports](https://resources.jetbrains.com/help/img/idea/2026.3/go_bind_ports.png)

6. In the Bind ports field, click Browse (![the Browse icon](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.menu-open.svg)).

7. In the Port Bindings dialog, click the Add button (![the Add button](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)). In the Host port column, type `8080`. Click the Container port column, type `8080`. Additionally, create the same binding for the port `40000`. Set Host IP to `127.0.0.1` for each binding.

8. In the Run options field, specify command-line options for Docker. For the example provided in the Dockerfile, disable the [security profile](https://docs.docker.com/engine/security/apparmor/) and add the `SYS_PTRACE` [Linux
capability](https://www.man7.org/linux/man-pages/man7/capabilities.7.html).

```DOCKERFILE
--security-opt="apparmor=unconfined" --cap-add=SYS_PTRACE
```

> **Warning:**
> These options relax container isolation: they disable the AppArmor profile and grant process-tracing permissions. Use them only for a development container that needs these permissions.

9. Click Run.

Procedure: Step 2. Create the Go Remote run/debug configuration

1. Click `Run | Edit Configurations`. Alternatively, click the list of run/debug configurations on the toolbar and select Edit Configurations.

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

3. In the Host field, type the host IP address (for example, `localhost`).

4. In the Port field, type the debugger port that you configured. In this example, it is `40000`.

5. Click OK.

![Create the Go Remote run/debug configuration for the Docker debugging](https://resources.jetbrains.com/help/img/idea/2026.3/go_create_the_remote_run_debug_configuration_for_docker.png)

Procedure: Step 3. Start the debugging process

1. In the Services tool window (`View | Tool Windows | Services`), expand `Docker | Containers`. Ensure that the created container is running and listens to the preconfigured debugger port.

2. Click the gutter near the line of code to place the breakpoint. For example, in [the provided code example](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/main.go), put the breakpoint on the line 23 (`message := fmt.Sprintf("Hello %s!", r.UserAgent())`).

Read more about breakpoints in [Breakpoints](using-breakpoints.html).

3. From the list of run/debug configurations on the toolbar, select [the created Go Remote
configuration](#step-2-create-the-go-remote-run-debug-configuration) and click the Debug <configuration_name> button (![the Debug button](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.startDebugger.svg)). Alternatively, 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` (VSCode), `⌃ ⌥ D` (VSCode (macOS)) to select the created Go Remote configuration.

4. Trigger the event at the breakpoint in your application. If you used [the provided code example](https://github.com/apronichev/documentation-code-examples/blob/master/debuggingTutorial/main.go), open [http://localhost:8080/](http://localhost:8080/) in a browser.

The following video demonstrates how to run a container and connect the debugger. It predates the loopback port bindings in the steps above. Use those bindings to keep the debugger port private.

[Video](https://resources.jetbrains.com/help/img/idea/2026.3/go_start_the_debugging_process_for_docker.mp4)

## Productivity tips

Procedure: Disconnect from the remote debugger

The On disconnect setting in [Go Remote](go-remote.html) determines how GoLand disconnects:

* Stop remote Delve process: stops Delve without asking whether to keep it running.

* Leave it running: keeps Delve running. If the application is still running, GoLand clears its breakpoints and resumes execution before closing the connection.

* Ask (default): if Delve was started with `--accept-multiclient`, the Stop Remote Delve dialog asks whether to stop it. Otherwise, GoLand stops Delve without this dialog.

1. Press `Ctrl+F2` (Windows), `⌘ F2` (macOS), `⌘ F2` (IntelliJ IDEA Classic (macOS)), `⌃ ⇧ .` (macOS System Shortcuts), `Ctrl+F2` (XWin), `Ctrl+F2` (GNOME), `Ctrl+2` (KDE), `Ctrl+F2` (Emacs), `Ctrl+F2` (Sublime Text), `Ctrl+F2` (Sublime Text (macOS)), `Shift+F5` (VSCode), `⇧ F5` (VSCode (macOS)) to end the debugging session.

2. If the Stop Remote Delve dialog opens, choose whether to stop Delve. To save your choice in the run configuration, select the checkbox that disables future prompts.

3. If you stop Delve while it is attached to an existing remote process that is still running, the Kill Remote Process dialog asks whether to terminate that process. Choose whether to stop the application or leave it running.

To reconnect to the same Delve server, start it with `--accept-multiclient`. Before disconnecting, set On disconnect to Leave it running in the run configuration, or decline to stop Delve when prompted.

