# How to work with OpenMPI projects in CLion

[OpenMPI](https://www.open-mpi.org) is an open-source implementation of the [Message Passing Interface (MPI)](https://www.mpi-forum.org) library, which is a standard designed to support high-performance parallel computing. OpenMPI combines technologies and resources from several MPI projects.

This tutorial will guide you through the steps of setting up, building, running, and debugging an OpenMPI project in CLion. The instructions are general, and you can apply them to your sources. To illustrate the steps, we use a simple C++ application that includes OpenMPI functions. The instructions are given for the case of working on macOS.

Procedure: 0. Before you start: install OpenMPI on your system

1. [Download](https://www.open-mpi.org/software/ompi) and [build](https://www.open-mpi.org/faq/?category=building#easy-build) OpenMPI. In case of errors, try the troubleshooting tips given on the same official FAQ page.

> **Tip:**
> Tip: if `make all install` fails with Permission denied, try running it with `sudo`.

2. As a simple check, run `mpicc` from the command line - your system should recognize the command.

Procedure: 1. Create a new project in CLion

1. Select `File | New | Project...` from the main menu or click New Project on the welcome screen.

2. ![Starting a new C++ project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_startproject.png)

In the left-hand pane, choose the project type (C++ Executable in our example).

Provide the project location and set the language standard.

Click Create.

3. CLion will generate a stub CMake project:

![Stub CMake project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_stubproject.png)

Procedure: 2. Add your source files

1. Copy your source files to the project folder.

In our example, the files are `openmpi_test.cpp` and `openmpi_test.h`. Copy-paste the code below if you would like to use them as a sample, or take your own files:

```CPLUSPLUS
#include <mpi.h>
#include <cstdio>

void print_processors() {

    // Initialize the MPI environment
    MPI_Init(nullptr, nullptr);

    // Get the number of processes
    int world_size;
    MPI_Comm_size(MPI_COMM_WORLD, &world_size);

    // Get the rank of the process
    int world_rank;
    MPI_Comm_rank(MPI_COMM_WORLD, &world_rank);

    // Get the name of the processor
    char processor_name[MPI_MAX_PROCESSOR_NAME];
    int name_len;
    MPI_Get_processor_name(processor_name, &name_len);

    // Print off a hello world message
    printf("Hello world from processor %s, rank %d out of %d processors\n",
    processor_name, world_rank, world_size);

    // Finalize the MPI environment.
    MPI_Finalize();
}
```

```CPLUSPLUS
#ifndef OPENMPI_TEST_OPENPMI_HELLO_H
#define OPENMPI_TEST_OPENPMI_HELLO_H

void print_processors();

#endif //OPENMPI_TEST_OPENPMI_HELLO_H
```

```CPLUSPLUS
#include "openmpi_test.h"

int main() {
    print_processors();
    return 0;
}
```

At this point, new files are not yet added to the CMake project structure, and OpenMPI code is not recognized by the IDE:

![OpenMPI files are not recognized                 until added to CMakeLists.txt](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_notrecognized_initially.png)

2. Add the files to CMake.

* To add a single file, click Add to CMake Project in the notification bar.

* To add multiple files, select them in the Project tree and call Add to CMake Project from the context menu.

Select the target, and CLion will add the files automatically:

![Adding a file to a CMake target](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_addtotarget.png)

Procedure: 3. Tune CMakeLists.txt and load the project

Open the `CMakeLists.txt` file and make the following changes:

1. Add this line before `add_executable`:

```CMAKE
find_package(MPI REQUIRED)
```

2. Add this line after `add_executable`:

```CMAKE
target_link_libraries(<your_project_name> PRIVATE MPI::MPI_CXX)
```

An example of `CMakeLists.txt` content:

```CMAKE
cmake_minimum_required(VERSION 3.25)
project(openmpi_test)

set(CMAKE_CXX_STANDARD 17)

# Add MPI Package to Project
find_package(MPI REQUIRED)

add_executable(openmpi_test main.cpp openmpi_hello.cpp)

# Link MPI libraries
target_link_libraries(openmpi_test PRIVATE MPI::MPI_CXX)
```

3. When you make changes in `CMakeLists.txt`, CLion shows the icon suggesting to reload the project structure. Click it or press the shortcut:

![Reloading CMake](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_reloadchanges_icon.png)

CMake reload and project build should finish successfully:

![Building an OpenMPI project after changing the CMakeLists.txt script](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openapi_build_success.png)

If there are errors, double-check your `CMakeLists.txt` and your OpenMPI installation.

You can find the binary in the `cmake-build-debug` folder (or another build location, in case you have changed it):

![Binary file in the build directory](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_binary.png)

Procedure: 4. Build your program

Use one of the options:

* Call `Build | Build Project` from the main menu.

For more information about this action, refer to [Build actions](build-actions.html).

* CLion automatically creates a configuration of the type [CMake Application](run-debug-configuration-makefile-application.html) for each of the targets detected in `CMakeLists.txt`.

To build a target using the configuration, select it in the switcher and click the hammer icon or press `Ctrl+F9` (Windows), `⌘ F9` (macOS), `⌘ F9` (IntelliJ IDEA Classic (macOS)), `⌘ ⌃ B` (macOS System Shortcuts), `Ctrl+F9` (XWin), `Ctrl+F9` (GNOME), `Ctrl+9` (KDE), `Ctrl+F9` (Emacs), `Ctrl+F9` (Sublime Text), `Ctrl+F9` (Sublime Text (macOS)), `⌘ B` (Xcode), `F7` (Visual Studio), `F7` (Visual Studio (macOS)), `F7` (ReSharper), `F7` (ReSharper (macOS)), `Ctrl+F9` (QtCreator), `⌘ F9` (QtCreator (macOS)), `F11` (NetBeans), `Ctrl+F9` (Eclipse), `⌘ B` (Eclipse (macOS)):

![Building a configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_build_config_toolbar.png)

> **Tip:**
> You can change configuration parameters and create more configurations in the Edit Configurations dialog.

Procedure: 5. (Optional) Configure CMake profiles

In [CMake profile](cmake-profile.html) settings, you can adjust build options, environment variables, build directory, and other parameters.

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

In this dialog, you can edit profile settings and create/remove profiles. For more information, refer to [CMake profiles](cmake-profile.html).

> **Tip:**
> When you start a project, CLion creates a Debug profile. If you need a release build, add another profile of the type Release.

![Debug and Release profiles](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_release_profile_added.png)

2. Project profiles are listed in the configuration switcher. Make sure to select the required profile before building a CMake configuration.

![Profiles in the configuration switcher](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_profiles_switcher.png)

Procedure: 5. Run the application

OpenMPI programs should run under special launchers, `mpiexec`, `mpirun`, or `orterun` (synonyms for the case of executing serial and parallel jobs in OpenMPI). To invoke them with the required program arguments, use CLion's Shell Script configuration.

1. In the main menu, go to `Run | Edit Configurations`.

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

![Adding a Shell Script configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_add_shellscript.png)

3. Adjust the configuration settings:

* Edit the configuration name.

* In Execute:, select Script text.

* In Script text, specify the command to run your program. In our example, it's `mpiexec -n 4 ./cmake-build-debug/openmpi_test`

![Shell Script configuration settings](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_shellscript_config_settings.png)

4. Save the settings, then select the newly created configuration in the switcher and click ![The Run button](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.execute.svg) or press `Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `⌘ ⌥ ⇧ R` (Xcode), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `Ctrl+F5` (ReSharper), `⌃ F5` (ReSharper (macOS)), `Ctrl+R` (QtCreator), `⌘ R` (QtCreator (macOS)), `F6` (NetBeans), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS)).

![Running a Shell Script                 configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_runshellscript_toolbar.png)

Your program should launch successfully. CLion will show the output in the Terminal tool window:

![OpenMPI program output in console](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_run_output.png)

Procedure: 6. Debug by attaching to process

In order to debug an OpenMPI application in CLion, you need to launch it first and then attach the debugger to each of the running processes.

1. Place [breakpoints](using-breakpoints.html) in your code by clicking in the left gutter next to the desired lines.

2. Add the following piece of code before each breakpoint:

```CPLUSPLUS
int i = 0;
while (!i)
    sleep(5);
```

3. Place a breakpoint on the `sleep(5);` line.

![Breakpoints in the code to debug](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_code_beforedebug.png)

4. Rebuild with `Build | Build Project` or [using a configuration](#build-profile-config).

Make sure the Debug profile is selected.

5. Run the Shell Script configuration. Select it in the switcher and click ![The Run button](https://resources.jetbrains.com/help/img/idea/2026.2/app.actions.execute.svg) or press `Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `⌘ ⌥ ⇧ R` (Xcode), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `Ctrl+F5` (ReSharper), `⌃ F5` (ReSharper (macOS)), `Ctrl+R` (QtCreator), `⌘ R` (QtCreator (macOS)), `F6` (NetBeans), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS)).

![Running a Shell Script                 configuration](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_runshellscript_toolbar.png)

6. Press `Ctrl+Alt+F5` (Windows), `⌥ ⇧ F5` (macOS), `⌥ ⇧ F5` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ F5` (macOS System Shortcuts), `Ctrl+Alt+5` (XWin), `Ctrl+Alt+5` (GNOME), `Ctrl+Alt+5` (KDE), `Ctrl+Alt+F5` (Emacs), `Ctrl+Alt+F5` (Sublime Text), `⌥ ⇧ F5` (Sublime Text (macOS)), `⌥ ⇧ F5` (Xcode), `Ctrl+Alt+P` (Visual Studio), `⌘ ⌥ P` (Visual Studio (macOS)), `Ctrl+Alt+F5` (ReSharper), `⌃ ⌥ F5` (ReSharper (macOS)), `Ctrl+Alt+F5` (QtCreator), `⌥ ⇧ F5` (QtCreator (macOS)), `Ctrl+Alt+F5` (NetBeans), `Ctrl+Alt+F5` (Eclipse), `⌥ ⇧ F5` (Eclipse (macOS)) or select `Run | Attach to Process` from the main menu.

7. In the dialog that opens, search for the process you want to attach to and click Attach with ....

![Attaching to process](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_attach_dialog.png)

8. In the Variables pane of the [Debug tool window](debug-tool-window.html) , select `i` and press `F2`. Set a non-zero value:

![Setting a variable value](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_debug_setvalue.png)

9. Continue debugging as usual.

With the debugger attached, you can use all the CLion debug features, such as [breakpoints of different types](using-breakpoints.html#set-line-breakpoint), [stepping actions](stepping-through-the-program.html), [memory](memory-view.html) and [disassembly](disassembly-view.html) view, [expressions evaluating](examining-suspended-program.html#evaluating-expressions), and so on.

![Stepping through a program with attached debugger](https://resources.jetbrains.com/help/img/idea/2026.2/cl_openmpi_debug_stepping.png)

10. Repeat the steps 6-9 to debug another process.

## See also

### External Links

[https://www.open-mpi.org](https://www.open-mpi.org)

### How tos

[Quick CMake tutorial](quick-cmake-tutorial.html) [Debugging](debugging-code.html) [Attach to process](attach-to-process.html)

### Concepts

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