# The Remote GDB Server configuration

> **TL;DR**
> Local OS: macOS / Linux / Windows
>
>
>
> Remote OS: any supporting gdbserver, SSH, and SFTP
>
>
>
> Required tool: [gdbserver](https://sourceware.org/gdb/onlinedocs/gdb/Server.html) on tagret
>
>
>
> Binary file synchronization: automatic
>
>
>
> Client debugger: bundled GDB / toolchain's GDB / custom GDB
>
>
>
> Build targets: CMake / Makefile / custom build target

The Remote GDB Server configuration builds your target locally, uploads the binary to the remote machine, launches it under gdbserver, and connects the CLion debugger.

Procedure: Create a Remote GDB Server configuration

1. In the main menu, go to Run | Edit Configurations, click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg), and select  Remote GDB Server from the list of templates.

2. Specify the following settings:

![Remote GDB Server configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_gdbserver_config.png)

* Target and Executable Select the target to be built ([CMake](quick-cmake-tutorial.html), [Makefile](makefiles-support.html), or [custom target](custom-build-targets.html)) and the executable to be uploaded remotely. Click the ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.settings.svg) button to [configure custom targets](custom-build-targets.html#customtarget-compdb) in the `Settings | Build, Execution, Deployment | Custom Build Targets` dialog.

* GDB Select the client debugger: bundled multiarch GDB (default), one of the toolchain debuggers, or a custom GDB binary.

* Credentials Select one of the existing SSH configurations from the drop-down list or click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.settings.svg) to create a new one. Provide the credentials for accessing your remote machine: ![remote credentials](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_gdbserver_credentials.png) > **Tip:** > You can also manage SSH configurations in `Settings | Tools | SSH Configurations`.

* Upload executable Your executable can be uploaded every time you start a debug session (Always) or upon the changes in the binary (Updated Only). You can also choose to skip uploading (None).

* Upload path Specify the remote folder where the executable will be placed.

* 'target remote' args Provide the medium to carry debugging packets (serial line or an IP network using TCP or UDP). See [gdb documentation](https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html#Connecting) for more details on connecting to a remote target.

* GDB Server Set the location of gdbserver on the remote machine. The default path is filled up automatically.

* GDB Server args Specify the arguments that will be passed to gdbserver: connection port, executable path, and additional arguments if required. By default, this field contains the port you provided in 'target remote' args and the path from Upload path followed by the binary name.

> **Note:**
> By default for CMake projects, this configuration builds your target using the currently selected [CMake profile](cmake-profile.html) and takes the binary from the Build directory folder.
>
>
>
> If your setup requires a cross-compiler toolchain, make sure to [create](how-to-create-toolchain-in-clion.html) it, configure a corresponding Debug profile, and switch to this profile before you start a session.

Procedure: Start a remote debug session

1. Make sure to select GDB as your toolchain debugger.

* On macOS and Linux, go to `Settings | Build, Execution, Deployment | Toolchains` and select one of the available GDB options in the Debugger field of the current toolchain.

* Note that on Windows, Remote GDB Server configurations can't be used with the [Visual Studio toolchain](quick-tutorial-on-configuring-clion-on-windows.html) since the [debugger](quick-tutorial-on-configuring-clion-on-windows.html#msvc-debugger) it employs is based on LLDB.

> **Tip:**
> Make sure your system's firewall allows connection to the remote GDB server.

2. After placing breakpoints in your code, select the newly created Remote GDB Server configuration, and press ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.startDebugger.svg) (`Shift+F9` (Windows), `⌃ D` (macOS), `⇧ F9` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ D` (macOS System Shortcuts), `Shift+F9` (XWin), `Shift+F9` (GNOME), `Shift+F9` (KDE), `Shift+F9` (Emacs), `Shift+F9` (Sublime Text), `⌃ D` (Sublime Text (macOS)), `⌘ R` (Xcode), `Alt+F5` (Visual Studio), `⌥ F5` (Visual Studio (macOS)), `Alt+F5` (ReSharper), `⌥ F5` (ReSharper (macOS)), `F5` (QtCreator), `⌘ Y` (QtCreator (macOS)), `Ctrl+F5` (NetBeans), `Alt+Shift+D` (Eclipse), `⌘ F11` (Eclipse (macOS))).

* You can find the build log in the Messages tool window: ![build log](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_gdbserver_buildlog.png)

* To monitor the process of uploading, switch to the File transfer window: ![file transfer](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_gdbserver_filetransfer.png)

* The Console tab of the Debug tool window shows the status of the GDB/gdbserver connection: ![remote debug console](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_gdbserver_console.png)

3. You can debug the program as usual: examine the variables, step through, evaluate expressions, and use all the other debug features.

![debugging with remote GDB server](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_gdbserver_debugging.png)

## See also

### External Links

[CLion Debugging Beyond the Basics - Part 3 - Beyond Local](https://blog.jetbrains.com/clion/2021/05/clion-debugging-beyond-the-basics-part-3-beyond-local) [Webinar Recording: Remote Development with CLion](https://blog.jetbrains.com/clion/2019/03/webinar-recording-remote-development-with-clion)

### How tos

[Complicated remote scenarios](complicated-remote-scenarios.html)