Targeting Linux from Visual Studio: WSL and Remote Machine

Visual Studio on Windows can build, deploy, and debug C++ applications running on Linux — without requiring you to leave the Windows IDE or maintain a separate Linux development environment. This capability works through two complementary mechanisms: the Windows Subsystem for Linux (WSL) for local Linux development and an SSH-based remote connection for physical machines, virtual machines, or cloud instances. When you build a Linux project, Visual Studio transfers your source files to the Linux machine, invokes GCC or Clang on that machine, copies back header files for full IntelliSense support in the Windows editor, and lets you set breakpoints and step through code using the full Visual Studio debugger — all over an SSH tunnel. This tutorial covers both paths end-to-end.

Prerequisites

Windows Side

Visual Studio 2017 or later
Linux and embedded development with C++ workload (see installation steps below)
Git for Windows (for cloning example projects)

Linux Side

GCC or Clang compiler
gdb debugger
openssh-server (remote machines only)
rsync, zip, make
ninja-build (for CMake projects)

Step 1 — Install the Linux Workload

Open the Visual Studio Installer

Open the Visual Studio Installer from the Windows Start menu (search for “Visual Studio Installer”). Click Modify next to your Visual Studio installation.

Select the Linux workload

On the Workloads tab, scroll down to Other Toolsets and check Linux and embedded development with C++.The workload includes:

Visual C++ for Linux Development
Visual C++ tools for CMake and Linux (selected by default)
Windows Universal C Runtime

Click Modify to install.

Step 2 — Prepare Your Linux Environment

Choose between WSL (recommended for local development) and a remote Linux machine.

WSL (Windows Subsystem for Linux)
Remote Linux Machine (SSH)

WSL runs a full Linux distribution inside Windows 10 or 11 without a VM or network configuration. Visual Studio detects WSL automatically.Install WSL and Ubuntu:

# Run in an elevated PowerShell or Windows Terminal
wsl --install

This installs WSL 2 with Ubuntu by default. Reboot if prompted.Install the required C++ tools inside WSL:

sudo apt-get update
sudo apt-get install g++ gdb make ninja-build rsync zip

g++ — GNU C++ compiler (GCC)
gdb — GNU debugger
make and ninja-build — build system backends
rsync and zip — used by Visual Studio to sync header files for IntelliSense

No SSH setup is needed for WSL — Visual Studio communicates directly with the WSL instance.

A remote Linux machine can be a physical server, a VM (Hyper-V, VMware, VirtualBox), or a cloud instance (Azure, AWS, GCP). Visual Studio connects over SSH.On Ubuntu/Debian:

sudo apt-get install openssh-server g++ gdb make ninja-build rsync zip
sudo service ssh start

On Fedora/RHEL:

sudo dnf install openssh-server gcc-g++ gdb make ninja-build rsync zip
sudo systemctl start sshd
sudo systemctl enable sshd

Make sure you know the machine’s hostname or IP address, username, and password (or have an SSH key configured).

If you don’t have a Linux machine, create a Linux VM on Azure in minutes: go to the Azure Portal, click Create a resource, and choose Ubuntu Server 22.04 LTS. The free tier (B1s) is sufficient for this tutorial.

Step 3 — Create a Linux C++ Project

Create a new project

In Visual Studio, go to File > New > Project. Filter by C++, Linux, and select Console Application (Linux). Click Next, name the project HelloLinux, and click Create.Visual Studio creates a project with a main.cpp:

#include <cstdio>

int main()
{
    printf("Hello from Linux!\n");
    return 0;
}

Set the target platform to Linux

In the project’s Property Pages (Project > Properties or Alt+Enter), confirm that:

Configuration Properties > General > Platform Toolset is set to GCC or the detected Linux toolset.
Debugging > Remote Debug Machine shows your Linux connection (configured in the next step).

Step 4 — Connect to Your Linux Machine

Connect to WSL
Connect via SSH

Visual Studio detects installed WSL distributions automatically. In the project Property Pages > Debugging, set Remote Debug Machine to your WSL distribution (e.g., Ubuntu-22.04 (WSL)).No further connection setup is required. Visual Studio uses a local pipe to communicate with WSL.

Open Connection Manager

Go to Tools > Options > Cross Platform > Connection Manager and click Add.

Enter connection details

Fill in the Connect to Remote System dialog:

Host name: IP address or hostname of your Linux machine
Port: 22 (default SSH port)
User name: your Linux username
Authentication type: Password or Private Key
Password: your Linux password (or path to your private key file)

Click Connect.

Trust the host key

On first connection, Visual Studio presents the server’s host key fingerprint. Verify it matches your machine and click Accept to store it.Visual Studio connects, then automatically copies header files from the remote Linux machine to a local cache (%LOCALAPPDATA%\Microsoft\Linux\HeaderCache\) for IntelliSense. This may take a minute for the first connection.

Step 5 — Build the Linux Project

With the connection established, building works the same as for Windows:

Press Ctrl+Shift+B or go to Build > Build Solution.
Visual Studio transfers the source files to the Linux machine using rsync.
It invokes the remote GCC/Clang compiler on the Linux machine.
Build output (compiler messages, errors, warnings) streams back to the Visual Studio Output window.
The compiled binary stays on the Linux machine.

A successful build shows output similar to:

1>------ Build started: Project: HelloLinux, Configuration: Debug x64 ------
1>Copying sources remotely to '192.168.1.100'...
1>Validating sources
1>Validating targets
1>Starting remote build
1>Compiling sources:
1>   main.cpp
1>main.cpp
1>Linking...
1>Build complete
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

The first build may be slower because Visual Studio copies all source files to the remote machine. Subsequent builds are incremental and only transfer changed files.

Step 6 — Debug on Linux

Debugging a Linux project from Visual Studio uses GDB running on the Linux machine, with the Visual Studio debugger UI on Windows serving as the front end.

Set a breakpoint

In main.cpp, click in the left margin next to the printf line. A red breakpoint dot appears.

Start debugging

Press F5 (or Debug > Start Debugging). Visual Studio:

Builds the project on the remote machine.
Deploys the binary.
Starts gdb on the Linux machine.
Connects Visual Studio’s debugger UI to gdb over SSH.
Runs the program until the breakpoint is hit.

Inspect state and step through code

The full Visual Studio debugging experience is available:

Autos / Locals / Watch windows show variable values from the Linux process.
F10 (Step Over), F11 (Step Into), Shift+F11 (Step Out) work normally.
The Call Stack window shows the Linux process’s call stack.
The Linux Console Window appears in Visual Studio and shows stdout/stderr from the remote process.

Continue and stop

Press F5 to continue running. The program exits and the debug session ends. Press Shift+F5 at any time to stop debugging.

Step 7 — CMake Projects Targeting Linux

For CMake projects, the workflow is identical to Windows CMake projects, but you select a Linux configuration in the preset dropdown. Visual Studio creates a CMakeSettings.json or recognizes a CMakePresets.json with a Linux configuration:

{
  "version": 3,
  "configurePresets": [
    {
      "name": "linux-debug",
      "displayName": "Linux Debug",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/linux-debug",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      },
      "vendor": {
        "microsoft.com/VisualStudioSettings/CMake/1.0": {
          "hostOS": ["Linux"]
        }
      }
    }
  ]
}

Select Linux Debug from the configuration dropdown in the toolbar, then build and debug exactly as described above. Visual Studio runs cmake on the remote Linux machine to generate Ninja build files, then invokes Ninja to compile.

Useful Linux Development Tips

IntelliSense on Linux Headers

After connecting to a Linux machine for the first time, Visual Studio downloads the Linux system headers (/usr/include, /usr/local/include, and compiler-specific headers) to a local cache. This enables full IntelliSense for Linux-specific APIs (POSIX, epoll, inotify, etc.) while editing on Windows. Headers are re-synced automatically when the connection is re-established.

Switching Between Windows and Linux Builds

If your project uses CMake, you can switch between a Windows build configuration and a Linux build configuration using the toolbar dropdown — no changes to source code required. This is the primary advantage of CMake for cross-platform projects.

Managing Multiple Linux Connections

Go to Tools > Options > Cross Platform > Connection Manager to add, remove, or edit SSH connections. Each connection is identified by host/user and can be the target for multiple projects.

WSL vs Remote Machine: Which to Use?

Use WSL for day-to-day local development — it is fast, requires no network, and integrates seamlessly with Windows tools. Use a remote machine (or VM) when you need to test on a specific Linux distribution, kernel version, or hardware architecture (such as ARM64), or when you are preparing for deployment to a server.

Linux Project Property Pages

Key properties for Linux projects are in Project > Properties:

Property	Location	Description
Remote Machine	Debugging	Selects the Linux connection from Connection Manager
Remote Build Root	General	Directory on Linux where source files are copied
Additional Include Directories	C/C++ > General	Extra include paths on the Linux machine
Additional Library Directories	Linker > General	Library search paths
Additional Dependencies	Linker > Input	Libraries to link (`pthread`, `dl`, etc.)
Compiler	C/C++ > General	GCC or Clang

Next Steps

With Linux development set up, you can target the same CMakeLists.txt codebase to build for Windows, Linux, and (with the Mobile workload) Android — all from a single Visual Studio instance. Explore the CMake Tutorial to deepen your understanding of cross-platform build configuration, or read about CMake projects in Visual Studio for the full feature reference.

Overview

Installation & Setup

Tutorials

Targeting Linux from Visual Studio: WSL and Remote Machine

Prerequisites

Windows Side

Linux Side

Step 1 — Install the Linux Workload

Step 2 — Prepare Your Linux Environment

Step 3 — Create a Linux C++ Project

Step 4 — Connect to Your Linux Machine

Step 5 — Build the Linux Project

Step 6 — Debug on Linux

Step 7 — CMake Projects Targeting Linux

Useful Linux Development Tips

Linux Project Property Pages

Next Steps

Build docs developers (and LLMs) love

Overview

Installation & Setup

Tutorials

Documentation Index

​Prerequisites

Windows Side

Linux Side

​Step 1 — Install the Linux Workload

​Step 2 — Prepare Your Linux Environment

​Step 3 — Create a Linux C++ Project

​Step 4 — Connect to Your Linux Machine

​Step 5 — Build the Linux Project

​Step 6 — Debug on Linux

​Step 7 — CMake Projects Targeting Linux

​Useful Linux Development Tips

​Linux Project Property Pages

​Next Steps

Build docs developers (and LLMs) love

Prerequisites

Step 1 — Install the Linux Workload

Step 2 — Prepare Your Linux Environment

Step 3 — Create a Linux C++ Project

Step 4 — Connect to Your Linux Machine

Step 5 — Build the Linux Project

Step 6 — Debug on Linux

Step 7 — CMake Projects Targeting Linux

Useful Linux Development Tips

Linux Project Property Pages

Next Steps