# Remote with local sources

> **TL;DR**
> Local client OS: macOS / Linux / Windows
>
>
>
> Remote host OS: Linux
>
>
>
> Sources location: locally with automatic synchronization to remote host
>
>
>
> Tools required on remote hosts: [rsync](https://rsync.samba.org/) for macOS/Linux/Windows clients, [tar](https://www.gnu.org/software/tar/) for Windows clients
>
>
>
> Project model: [CMake](quick-cmake-tutorial.html) / [Makefile](makefiles-support.html)
>
>
>
> Required plugin (bundled, enabled by default): FTP/SFTP/WebDAV Connectivity

This remote mode enables you to work in CLion on a macOS, Linux, or Windows desktop targeting a remote Linux machine connected via [SSH](https://en.wikipedia.org/wiki/Secure_Shell). You can choose any Linux-based target, including embedded systems on single-board computers like [Raspberry Pi](https://www.raspberrypi.org/). Also, your program can be launched on a cloud platform or, for example, inside a [Docker](clion-toolchains-in-docker.html) container.

In this mode, the IDE instance runs locally, and your source files are also placed on the local client, with automatic synchronization to the remote host. On the remote host side, CLion performs compilation and build using host compilers and CMake/make, uses host GDB for debug, and runs the application on the remote target.

## Steps of the workflow

CMake:

1.

[Create a Remote toolchain](#remote-toolchain):

* provide credentials and check the connection,

* wait for tools detection, provide the paths manually if required.

2.

Set the Remote toolchain as default or [create an associated CMake profile](#CMakeProfile).

3.  If needed, adjust path mappings in the [deployment entry](#deployment-entry).

4.

Use the default profile or select the profile from step 2 for build, run, and debug.

Makefile:

1.

[Create a Remote toolchain](#remote-toolchain):

* provide credentials and check the connection,

* wait for tools detection, provide the paths manually if required.

2.

Switch to the remote toolchain in `Settings | Build, Execution, Deployment | Makefile`.

3.  If needed, adjust path mappings in the [deployment entry](#deployment-entry).

4.

Call `Tools | Makefile | Clean and Reload Makefile Project`.

In the configuration settings, point Executable to the remote binary.

Procedure: Windows client specifics

When working on a Windows client, keep in mind the following:

* Due to the IntelliJ platform [issue](https://youtrack.jetbrains.com/issue/IDEA-135546), you need to set the [property](tuning-the-ide.html#configure-platform-properties) value `idea.case.sensitive.fs=true` in the `idea.properties` file (to access the property file, select `Help | Edit Custom Properties...` from the main menu), then restart CLion with cache reset (`File | Invalidate Caches / Restart...`).

* For files synchronization on Windows, by default, CLion relies on its own Remote Host Access and compression on the host side using the tar utility. This mechanism works slower than synchronization with the Rsync tool on macOS and Linux. You can enable Rsync synchronization on Windows by selecting the Use rsync for download/upload/sync checkbox in [deployment settings](deployment-connection-tab.html#sftp-settings).

Procedure: Create a toolchain with remote credentials

1. Go to `Settings | Build, Execution, Deployment | Toolchains`.

2. Click ![plus icon](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) and select Remote Host:

![Adding a remote toolchain](https://resources.jetbrains.com/help/img/idea/2026.2/cl_toolchains_addremote.png)

3. If you already have an [SSH configuration](create-ssh-configurations.html), select it from the Credentials list:

![Selecting an SSH configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_toolchains_remote_sshconfigslist.png)

Otherwise, click ![](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.settings.svg) next to the Credentials field. In the dialog that opens, create an SSH configuration and provide the credentials for accessing you remote machine:

![Creating a new SSH configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_toolchaincredentials.png)

4. After establishing the connection, CLion attempts to detect the tools in default remote locations `/usr/bin/cmake` and `/usr/bin/gdb` (or using the full paths, if you have provided manually). When the checks finish successfully, the toolchain is ready for use:

![Remote toolchain configured successfully](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_toolchainsuccess.png)

5. You can make the newly created toolchain the default one (for this, move it to the top of the toolchains list by clicking ![move up](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.moveUp.svg)![move down](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.moveDown.svg)). When set as default, the remote toolchain is used for all the projects you create and open in CLion.

For CMake projects, if you set the remote toolchain as default, the default CMake profile will connect to it automatically, so you do not need to configure a separate CMake profile for it.

Procedure: (CMake) Create the corresponding CMake profile

* Go to `Settings | Build, Execution, Deployment | CMake`.

* Click ![plus icon](https://resources.jetbrains.com/help/img/idea/2026.2/app.expui.general.add.svg) to create a new [CMake profile](cmake-profile.html), and connect it to your remote toolchain using the Toolchain field:

![CMake profile for the remote toolchain](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_cmakeprofile.png)

Alternatively, set the remote toolchain [as default](#RemoteAsDefault) and select Use default.

* Apply the changes.

Procedure: (Makefile) Select the remote toolchain in Makefile setting

1. Go to `Settings | Build, Execution, Deployment | Makefile`.

2. Select your remote toolchain in the Toolchain field:

![Selecting a remote toolchain for Makefile](https://resources.jetbrains.com/help/img/idea/2026.2/cl_makefile_toolchain_remote.png)

Alternatively, set the remote toolchain [as default](#RemoteAsDefault) and select Use default.

3. Apply the changes.

4. Use the File Transfer tool window (`View | Tool Windows | File Transfer`) to monitor the progress of file synchronization:

![Upload notification](https://resources.jetbrains.com/help/img/idea/2026.2/cl_makefile_upload_remote.png)

Procedure: Check and adjust the deployment configuration

When you create a connection entity for the remote toolchain, CLion puts it in the list of [server access configurations](settings-deployment.html) in `Settings | Build, Execution, Deployment | Deployment`.

* CLion automatically configures the paths for your project code synchronization. Use the Mappings tab to change the default mappings (for example, to set a particular remote directory for the copied sources instead of the default `tmp` folder):

![path mapping for file synchronization](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_pathmappings.png)

* CMake:

For CMake projects, CLion automatically triggers synchronization when you change deployment settings. You can monitor the process in the File Transfer tool window (`View | Tool Windows | File Transfer`):

![file transfer tool window](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_filetransfer.png)

When uploading your project to the remote machine, CLion uses the directory containing the top-level `CMakeLists.txt` as a project root ([CPP-23995](https://youtrack.jetbrains.com/issue/CPP-23995)). If your top `CMakeLists.txt` is located in a different subdirectory, change the local path in the Mappings tab.

Makefile:

When uploading a Makefile project to the remote machine, CLion uses the directory containing the Makefile as a project root (see the general ticket [CPP-23995](https://youtrack.jetbrains.com/issue/CPP-23995)). If your Makefile is located in a different subdirectory, change the local path in the Mappings tab.

* You can set up remote development without source synchronization to avoid unnecessary file duplication when your local and remote machines share a mounted volume (for example, in the case of using a [Docker](docker.html) container) or when 3rd-party synchronization is configured outside of CLion.

For this, open the Connection tab and change the connection type to Local or mounted folder, then set up the path mappings (for Docker, specify the mapped volumes).

![No source synchronization](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_deploy_nosync_docker.png)

CLion always downloads the CMake build folder on CMake reload. However, this can be skipped if the Local or mounted folder deployment type is selected, and the CMake build folder is stored under one of the existing path mappings.

* The deployment process for SFTP connections can be sped up with the help of the Rsync tool. On macOS and Linux, Rsync support is enabled by default, on Windows, you need to enable it by selecting the Use rsync for download/upload/sync checkbox in [deployment settings](deployment-connection-tab.html#sftp-settings).

Procedure: Excluded paths

By default, CLion analyzes and synchronizes all the directories listed in `CMakeLists.txt`. However, if you [exclude](project-analysis.html#exclude_directory_from_project_analysis) a directory using the Mark Directory as | Excluded action, it will be marked as Excluded path for the remote deployment and will not be synchronized with the remote machine. This is performed automatically when you exclude a folder before configuring a remote toolchain.

You can check and adjust the excluded paths in the dedicated tab of the [deployment entry](#deployment-entry) settings:

![Excluded paths](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_excluded_paths.png)

* If you mark a directory as excluded when there is a remote toolchain configured and the project has been synchronized already, CLion will suggest that you update the excluded paths. After the update, the excluded folder will be synchronized further.

![Suggestion to update the deployment excluded paths](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_mark_as_excluded.png)

* If you un-exclude a previously excluded directory, CLion will suggest to update the list of the excluded paths and re-upload the folder to the remote host.

![Suggestion to update the deployment excluded paths and re-upload the folder](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_unmark_excluded.png)

Procedure: Resync header search paths

* To resolve your code correctly, CLion synchronizes header search paths with all the content from the remote machine to the local client. For example, even though standard library headers are taken from the target, you can navigate to them as if you were working locally in the CLion editor.

However, header search paths synchronization can be time-consuming, so CLion performs it automatically only upon the initial file transfer. After that, it is not triggered by CMake or Makefile reloads. So every time you switch the compiler or make changes in your project dependencies, make sure to update header search paths manually by calling `Tools | Resync with Remote Hosts`.

> **Note:**
> Note that you need to call Resync with Remote Hosts manually for every change in your project dependencies or compilers.

You can also switch to automatic synchronization: set the clion.remote.resync.system.cache key in the Registry (go to `Help | Find Action` or press `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `⌘ ⇧ A` (Xcode), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (ReSharper), `⌘ ⇧ A` (ReSharper (macOS)), `Ctrl+Shift+A` (QtCreator), `⌘ ⇧ A` (QtCreator (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)), type Registry, and search for the key by name).

Starting with version 2022.3, CLion uses [pigz](https://zlib.net/pigz/) for compression on the remote host to synchronize the header search paths back to the local host, instead of gzip. This multithreaded gzip implementation makes things work faster.

Procedure: Build, run, debug

CMake:

Now that you have a remote toolchain and the corresponding CMake profile configured, you can build, run, and debug your application and tests in the completely remote way by selecting the proper CMake profile in the Run/Debug configuration switcher:

![cmake profile for remote](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_profile.png)

Below you can find a demo showing how the application output changes depending on the OS that it runs on. Having macOS as a local system, we connect remotely to the Ubuntu target and check the OS name. In this example, code highlighting depends on the OS identifier, so when we switch the CMake profile or [resolve context](switching-resolve-context.html), CLion highlights the corresponding code branch:

![choose build configuration for remote run](https://resources.jetbrains.com/help/img/idea/2026.2/cl_remote_runapp.animated.gif)

Makefile:

1. Create a new [Native Application](makefiles-support.html#create-makefile-config) configuration or edit an existing one.

2.

In the Executable field, point CLion to the remote binary.

> **Tip:**
> To quickly find out the path to your project directory on the remote host, call `Tools | Open Remote Host Terminal`.

![Remote executable in the configuration settings](https://resources.jetbrains.com/help/img/idea/2026.2/cl_makefile_remote_config.png)

3. Save the configuration and use it to run or debug your Makefile application remotely.

> **Tip:**
> For both CMake and Makefile configurations, you can set [remote external tools](settings-tools-remote-ssh-external-tools.html) as a Before launch step.

Procedure: Set environment variables

1. To configure environment variables for the remote OS, specify them in the beginning of the `.bashrc` file, before the `# If not running interactively, don't do anything` line.

If your primary shell is not bash, follow the instructions for that particular shell or add `PermitUserEnvironment yes` to the `sshd_config` file, restart the sshd service, and then configure the variables in `~/.ssh/environment`.

Procedure: Enable IPv6 support

* To connect to [IPv6](https://en.wikipedia.org/wiki/IPv6) networks, you need to make adjustments in CLion [JVM options](tuning-the-ide.html#configure-jvm-options):

1.

Run `Help | Edit Custom VM Options` from the main menu. In the `*.vmoptions` file that opens, delete the `-Djava.net.preferIPv4Stack=true` line and add the following lines:

```CONSOLE
-Djava.net.preferIPv4Stack=false
-Djava.net.preferIPv6Stack=true
-Djava.net.preferIPv6Addresses=true
```

2. Restart CLion.

* In order to use hostnames instead of raw addresses, open `C:\Windows\System32\Drivers\etc\hosts` as Administrator on Windows or `/etc/hosts` as superuser on macOS/Linux and map the required addresses to the corresponding hostnames.

Each address should be placed on a separate line, followed by at least one whitespace and a list of whitespace-separated hostnames, for example:

```CONSOLE
f381::171d:c61c:c7f3:3a56      my.dev.host1 my.dev.host2
f381::171d:c61c:c7f3:3a26%en0  my.dev.host3
```

* On macOS, you also need to specify the list of the banned network interfaces:

1.  Press   `Ctrl+Shift+A` (Windows), `⌘ ⇧ A` (macOS), `⌘ ⇧ A` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ P` (macOS System Shortcuts), `Ctrl+Shift+A` (XWin), `Ctrl+Shift+A` (GNOME), `Ctrl+Shift+A` (KDE), `Escape, X` (Emacs), `Ctrl+Shift+P` (Sublime Text), `⌘ ⇧ P` (Sublime Text (macOS)), `⌘ ⇧ A` (Xcode), `Ctrl+Shift+A` (Visual Studio), `⌘ ⇧ A` (Visual Studio (macOS)), `Ctrl+Shift+A` (ReSharper), `⌘ ⇧ A` (ReSharper (macOS)), `Ctrl+Shift+A` (QtCreator), `⌘ ⇧ A` (QtCreator (macOS)), `Ctrl+I` (NetBeans), `Ctrl+Shift+A` (Eclipse), `⌘ 3` (Eclipse (macOS)) or choose `Help | Find Action` from the main menu. In the popup that opens, start typing `Registry`, select the corresponding item 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)), `⏎` (Xcode), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (ReSharper), `⏎` (ReSharper (macOS)), `Enter` (QtCreator), `⏎` (QtCreator (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

2. Find the deployment.macOs.bannedInterfaces key and set a comma-separated list of the interfaces to be banned, for example `awdl0,bridge0,en1,en2,lo0,p2p0,utun0,utun1`.

## See also

### How tos

[Remote development overview](remote-development.html)

### Concepts

[Run/Debug Configurations](run-debug-configuration.html) [CMake profiles](cmake-profile.html)

### Procedures

[Building](build-actions.html) [Deploying](deploying-applications.html) [Debugging](debugging-code.html)

### How tos

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

### External Links

[CLion Blog: Using Docker with CLion](https://blog.jetbrains.com/clion/2020/01/using-docker-with-clion/) [Webinar Recording: Remote Development with CLion](https://blog.jetbrains.com/clion/2019/03/webinar-recording-remote-development-with-clion) [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)