Install a C++ Compiler — Step by step

Before you begin — choose the right option

Pick the method that matches how you plan to work:

• Windows native (recommended): MSYS2 + Mingw-w64 (GCC) or Visual Studio/Build Tools (MSVC) if you prefer the Microsoft toolchain.
• Linux: Use your distro package manager to install gcc/g++ and related tools.
• macOS: Use Apple’s command line tools (Clang) or Homebrew to install GCC.
• WSL (Windows Subsystem for Linux): If you want a Linux-style environment on Windows, enable WSL and install Ubuntu (recommended for tutorials).

Each section below contains a concrete, step-by-step procedure with the exact commands to run (where applicable) and verification steps.

Windows — Recommended: MSYS2 + MinGW-w64 (GCC)

MSYS2 is a minimal unix-like environment on Windows and is a reliable way to get up-to-date GCC toolchains.

1. Download and run the MSYS2 installer.
   (Get the official MSYS2 installer executable and run it.)
2. Install to a short path (recommended): e.g. C:\msys64. Accept defaults or choose another drive if needed.
3. Open the MSYS2 shell: use the Start menu and open MSYS2 MSYS first.
4. Update the package database and core packages.
   Run these commands in the MSYS2 shell. After the first command, the shell may close — reopen the shell and continue as noted.

   pacman -Syu
   # If the shell closes, re-open "MSYS2 MSYS" then run:
   pacman -Su

5. Install the MinGW-w64 toolchain (64-bit) and common build tools.

   pacman -S --needed base-devel mingw-w64-x86_64-toolchain

   When prompted, press Enter to accept package selections, or answer y to confirm.
6. Use the correct shell for compiling: open the MSYS2 MinGW 64-bit shell from Start — it places the MinGW bin on PATH automatically.
7. Verify the compiler:

   g++ --version
   gcc --version

   You should see the installed version numbers for g++ and gcc.
8. Compile a quick test file: create hello.cpp with this content and compile:

#include <iostream>
using namespace std;
int main(){ cout << "Hello from MSYS2 + GCC!\n"; return 0; }

g++ hello.cpp -o hello.exe
./hello.exe

9. Tip: If you want to use the compiler from Windows CMD or PowerShell, add the MinGW bin directory to your Windows PATH environment variable (e.g. C:\msys64\mingw64\bin). Using the MSYS2 shells is simpler because they configure environment automatically.

Windows — Alternative: MinGW-w64 standalone installer

Quick installer option without the MSYS2 environment. Good for simple setups.

1. Download the MinGW-w64 installer executable and run it.
2. Choose architecture: choose x86_64 for 64-bit systems and select the recommended threading and exception model (defaults are usually fine).
3. Install to a folder you control: e.g. C:\mingw-w64 or C:\Program Files\mingw-w64.
4. Add the bin folder to PATH:
   Example of command-line that appends to your user PATH (run in an elevated prompt if required):

   setx PATH "%PATH%;C:\mingw-w64\mingw64\bin"

   After running setx, open a new Command Prompt to see the change.
5. Verify:

   g++ --version

6. Compile a test:

   g++ hello.cpp -o hello.exe
   hello.exe

7. If you see "g++ not recognized", confirm that the bin path you added actually contains g++.exe and that you opened a new shell after modifying PATH.

Windows — Alternative: Visual Studio (MSVC) / Build Tools

If you prefer Microsoft’s toolchain and Visual Studio IDE, use Visual Studio Community or the Build Tools.

1. Run the Visual Studio Installer. Choose either Visual Studio (full IDE) or "Build Tools for Visual Studio" (smaller, command-line oriented).
2. Select the workload: choose "Desktop development with C++" (this installs MSVC, headers, libraries and the Windows SDK).
3. Install and restart if required.
4. Open the "Developer Command Prompt for VS" or "x64 Native Tools Command Prompt": The environment scripts configure PATH so you can run cl directly.
5. Compile with MSVC:

   cl /EHsc hello.cpp

   That produces hello.exe. Use the Developer Command Prompt so cl and SDK tools are on PATH.
6. Visual Studio gives IDE features (debugger, project system). Use MSVC when you need tight Windows integration or Visual Studio debugging features.

Windows — Optional: Windows Subsystem for Linux (WSL)

Runs a real Linux distribution on Windows. Great for using native Linux toolchains.

1. Enable WSL (modern Windows 10/11): open an elevated PowerShell and run:

   wsl --install -d ubuntu

   This installs WSL and a default Linux distro (typically Ubuntu). After install, you will create a Linux username/password.
2. Open the installed Linux distribution (e.g., Ubuntu) from Start.
3. Install build tools inside WSL:

   sudo apt update
   sudo apt install build-essential

4. Verify:

   g++ --version

5. Compile & run inside WSL:

   g++ hello.cpp -o hello
   ./hello

6. WSL files live in the Linux filesystem — you can edit them from Windows editors, but prefer saving projects inside the Linux home directory for best performance.

Linux — Typical distro steps (Ubuntu / Debian / Fedora / Arch)

Use your distro package manager. Examples below show the canonical commands.

1. Ubuntu / Debian:

   sudo apt update
   sudo apt install build-essential

   This installs gcc, g++, make, and required headers.
2. Fedora / RHEL (dnf):

   sudo dnf install gcc-c++ make

3. Arch / Manjaro (pacman):

   sudo pacman -Syu
   sudo pacman -S base-devel gcc

4. Verify & compile:

   g++ --version
   g++ hello.cpp -o hello
   ./hello

macOS — Command Line Tools (Clang) or Homebrew GCC

Two common approaches: Apple’s Clang (works out of the box for many projects) or Homebrew for GNU GCC.

1. Install Apple command-line tools (Clang):

   xcode-select --install

   Follow the prompts to install. After installation, clang and g++ (as a Clang front-end) are available.
2. Optional — install Homebrew and then GCC:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   brew install gcc

   Homebrew places GNU compilers as e.g. g++-12 (version number appended). You can call the exact binary or create a symlink if desired.
3. Verify:

   clang --version
   g++ --version   # may be clang front-end on macOS unless you installed GNU gcc

Verify installation & compile a sample program

1. Create hello.cpp:

   #include <iostream>
   using namespace std;
   int main(){ cout << "Hello, world!\n"; return 0; }

2. Compile with g++ (GCC):

   g++ hello.cpp -o hello
   ./hello   # on Windows use hello.exe or .\hello.exe

3. Compile with MSVC (Developer Command Prompt):

   cl /EHsc hello.cpp

4. If compilation succeeds and the program prints the message, your compiler is configured correctly.

Troubleshooting — common issues and fixes

1. Command not found / g++ not recognized:

   Usually PATH is not set. On Windows, ensure the directory containing g++.exe is in your user or system PATH. Open a fresh terminal after changing PATH.

2. MSYS2 pacman operations open/close the terminal:

   Follow the update sequence: run pacman -Syu, if the shell closes reopen and run pacman -Su to finish.

3. Linker errors (undefined references):

   Ensure you link required libraries and compile both object files. Use -l flags to link libraries and ensure correct order.

4. Permission denied when running compiled binary:

   On Linux/macOS, make the file executable with chmod +x hello. On Windows, ensure antivirus is not blocking executables.

5. Using IDEs (VS Code, CLion, Visual Studio):

   Install the compiler first, then configure the IDE to use that toolchain (path to g++ or Global Tools). Many IDEs auto-detect toolchains if PATH is set properly.

6. Which compiler to pick?

   Use GCC for portability and alignment with Linux/Unix tutorials, MSVC for Windows-specific development, and Clang on macOS if you prefer Apple toolchain.

Extra: environment setup tips & best practices

1. Use MSYS2 MinGW shell on Windows for a consistent Unix-like experience and up-to-date GCC packages.
2. Keep toolchains updated: for MSYS2 use pacman -Syu, for Linux use your package manager, and for Homebrew use brew update && brew upgrade.
3. Project layout: keep source files in a project folder, use a build system (Make/CMake) for non-trivial projects instead of compiling by hand each time.
4. Use a modern editor: Visual Studio Code + C/C++ extension is lightweight and works well with GCC/MSVC/Clang.

Summary checklist