# The Remote Debug configuration > **TL;DR** > Local OS: macOS / Linux / Windows for GDB, macOS / Linux for LLDB > > > > Remote OS: any supporting gdbserver for GDB, macOS / Linux or another supporting lldb-server for LLDB > > > > Required tool: [gdbserver](https://sourceware.org/gdb/onlinedocs/gdb/Server.html) or [lldb-server](https://lldb.llvm.org/man/lldb-server.html) on target > > > > Binary and symbol file synchronization: manual > > > > Client debugger: bundled GDB or bundled LLDB, toolchain's GDB, custom GDB The Remote Debug configuration allows you to debug remotely under gdbserver or lldb-server. Use this configuration if you already have the executable with debug information and don't need CLion to build the project for you. This configuration is independent of a particular build system or project format. > **Tip:** > The terms we use below: a local machine (host) is where you run CLion and the GDB/LLDB client, while a remote machine (target) is where you launch the application under gdbserver/lldb-server. The Remote Debug configuration allows you to remotely debug applications built with any build system. The only requirement is for the debug symbols to be present on the local machine. ## Target platforms GDB/gdbserver: There are no restrictions on target environment in case it supports gdbserver. Your program can run remotely on any OS including Linux-based embedded like [Raspbian OS](https://www.raspberrypi.org/software/operating-systems/) (refer to [Raspberry Pi OS Guide](https://www.pcwdld.com/raspbian-raspberry-pi-os-guide)), on a cloud platform, or inside a [Docker](docker.html) container. You can connect to any GDB stub that complies with the remote gdbserver protocol: for example, [Qemu](https://en.wikibooks.org/wiki/QEMU/Debugging_with_QEMU) to debug OS kernels or [OpenOCD](https://openocd.org) to debug flashed firmware. CLion's bundled GDB, which is used as a client debugger by default, is built with multiarch support, which makes it suitable for remote cross-platform debug in various Linux/Windows/macOS and embedded cases. Find the full list of the supported targets below. Procedure: Remote targets supported by the bundled GDB ```CONSOLE i686-pc-mingw32 i686-w64-mingw32 x86_64-w64-mingw32 i686-linux-gnu x86_64-linux-gnu aarch64-linux-gnu alpha-linux-gnu arm-linux-gnu arm-linux-gnueabi arm-linux-gnueabihf hppa-linux-gnu ia64-linux-gnu m68k-linux-gnu m68k-rtems mips-linux-gnu mipsel-linux-gnu mips64-linux-gnu mips64el-linux-gnu powerpc-linux-gnu powerpc-linux-gnuspe ``` LLDB/lldb-server: You can target macOS, Linux, Android, Apple TV/Apple Watch, and other platforms that support lldb-server. See [Local system](https://lldb.llvm.org/use/remote.html#local-system) in the LLDB documentation. ## General steps of the workflow Find below a brief description of the steps to take for remote GDB/LLDB debug. More details for each step are given in the next chapters. 1. Prepare a binary with debug information. If required, use a cross-platform toolchain. In the case of remote LLDB, the debugger does not download any debug symbols or system libraries automatically, so they should be present on the local machine. For cross-platform debug from macOS to Linux or from Linux to macOS, use cross-compilation via [musl](https://musl.libc.org/) (or the alternatives), which will be shipped with the required libraries. 2. Make sure to place the binary on the remote machine and symbol file on the local machine. Usually, the debug executable itself works well as a symbol file, or this can be a separate file as well. > **Note:** > As Remote Debug configuration does not synchronize your files, you will need to keep track of binaries and symbol files and synchronize them manually upon any change. 3. In CLion, [create](#remote-config) a Remote Debug configuration. The settings you specify are crucial for the debugger to be able to stop on breakpoints during a remote session, so we recommend you double-check the configuration set up. 4. [Launch](#launch-remote-debug) the program under gdbserver/lldb-server on the remote machine. 5. Back in CLion, start [debugging the configuration](#start-remote-debug) you created on step 3. Procedure: Create a Remote Debug configuration 1. Go to Run | Edit Configurations, click ![](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app.expui.general.add.svg), and select Remote Debug from the list of templates. 2. ![Remote Run/Debug Configuration](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_remoteConfig.png) Select the client debugger (bundled GDB / bundled LLDB, one of the toolchain GDB debuggers, or a custom GDB binary) and provide the corresponding settings: GDB: * 'target remote' args – the remote system's address in the following format: ``` : ``` For example: ``` 127.0.0.1:1234 ``` You can also use an [alternative format](https://sourceware.org/gdb/onlinedocs/gdb/Connecting.html#Connecting). * Symbol file. This is the local machine path to the file with debug symbols, which can be a non-stripped copy of the executable running on the target or an [ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) file containing only the debug info. > **Tip:** > If you are debugging a shared object library, avoid specifying the `.so` file as a symbol file. With `.so` as a symbol file, the debugger resolves the source location to two places: one to the actual address in memory, and the other to a file address within the `.so` file, which is not a valid memory address. As a result, stepping and other debugging actions do not work correctly. Recent versions of GDB clients can transfer symbols from gdbserver automatically, so leaving this field empty may also work well if the executable running on the target is a non-stripped binary. * Sysroot is used by GDB client to access copies of target libraries with debug symbols on your local system, allowing you to set breakpoints and find source lines in the library code. > **Tip:** > Most of the recent GDB versions download these files automatically, so the field is optional. However, note that automatic download may slow down the debugging process significantly. > > > > You may choose to manually copy the libraries to a non-default local directory. If so, provide the path in this field and GDB will use it. LLDB: * 'process connect' url. Use the following notation: ``` connect://: ``` For example: ``` connect://127.0.0.1:1234 ``` * Symbol file. This is the local machine path to the file with debug symbols, which can be a non-stripped copy of the executable running on the target or an [ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) file containing only the debug info. > **Tip:** > If you are debugging a shared object library, avoid specifying the `.so` file as a symbol file. With `.so` as a symbol file, the debugger resolves the source location to two places: one to the actual address in memory, and the other to a file address within the `.so` file, which is not a valid memory address. As a result, stepping and other debugging actions do not work correctly. CLion employs lldb-server in the [g\[dbserver\]](https://lldb.llvm.org/man/lldb-server.html) mode, which requires you to transfer all the files manually. * Sysroot is used by LLDB client to access copies of target libraries with debug symbols on your local system, allowing you to set breakpoints and find source lines in the library code. > **Note:** > You must specify sysroot to debug binaries built without cross-compilation on a remote platform that differs from the host (for example, if you're debugging from a macOS host and the remote Linux machine runs a binary linked to Linux system libraries). * * Path mappings. Use this pane to provide the paths on the target machine (in the Remote column) to be mapped to local paths on the host (in the Local column). Procedure: Launch your program remotely under gdbserver/lldb-server To launch your application on the target, you can use the remote terminal or invoke CLion's built-in [SSH terminal](running-ssh-terminal.html) and [perform port forwarding](security-model.html#port_forwarding). GDB: Run gdbserver using the following command: ``` gdbserver : ``` ![remote ssh terminal](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_remoteTerminal.png) Alternatively, you can connect over the serial port: ``` gdbserver ``` If you prefer to establish a serial line connection, indicate the device name instead. LLDB: For LLDB, start lldb-server with a command like `lldb-server g *:1234 ./binary`. On macOS, use debugserver as lldb-server: ``` debugserver : ``` For example: ``` debugserver 192.168.1.226:1234 ./binary ``` > **Tip:** > By default, debugserver is located either in `/Applications/Xcode.app/Contents/SharedFrameworks/LLDB.framework/Versions/A/Resources/debugserver` (as part of the Xcode distribution) or in `/Library/Developer/CommandLineTools/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/debugserver` (as part of the command-line tools). Once launched, gdbserver/lldb-server will suspend the program at the entry point and wait for the client debugger to connect. Procedure: Start a remote debug session In CLion, once you've placed breakpoints in your code, select the Remote Debug configuration and start the debug ![](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app.actions.startDebugger.svg) session. CLion’s debugger will connect to the running remote process. The terminal will show the Remote debugging from host.. message, and you can also check the debugger console for the Debugger connected to.. message. Now you can inspect your code as if it was running locally ([step through](stepping-through-the-program.html), [examine variables](examining-suspended-program.html), etc.). ![debug via gds/gdbserver](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_remoteDebugWindow.png) > **Note:** > If your program doesn't stop at breakpoints set in the IDE, double-check that the symbol file and path mappings are correctly specified in your Remote Debug configuration settings. Procedure: Debug shared libraries To debug shared libraries, add the following commands in `~/.gdbinit` or `.lldbinit` on the local machine. For more information about accessing and editing the script, refer to [Using .gdbinit/.lldbinit configuration files](configuring-debugger-options.html#gdbinit-lldbinit). * set [solib-search-paths](http://visualgdb.com/gdbreference/commands/set_solib-search-path) for GDB However, by default, this command is executed on the debugger startup before attaching to the remote target (see the corresponding [issue](https://youtrack.jetbrains.com/issue/CPP-7322)). As a workaround for this, you can use [GDB hooks](https://sourceware.org/gdb/onlinedocs/gdb/Hooks.html): ```CONSOLE define target hookpost-remote set solib-search-path /path/to/my.so:/path/to/sysroot:/path/to/vendorlibs break main # if you also need the debug sessions to pause at the beginning end ``` This way, GDB will execute `set solib-search-path` specified in the hook every time the remote target is connected. * `settings set target.exec-search-paths /path/to/libs` for LLDB ## 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) [LLDB Remote Debugging](https://lldb.llvm.org/use/remote.html)