How to setup gdb and Eclipse to debug C++ files on macOS Sierra

Last Update: 16 October 2018

Using gdb debugger on macOS is no longer straightforward since Xcode stopped using it and replaced it with lldb. Starting from macOS Sierra, there are several steps to follow to make it work.

Install gdb

The easiest way to install gdb is by using Homebrew: “the missing package manager for macOS”. If you don’t have it installed, open your Terminal prompt and write this command:

/usr/bin/ruby -e "$(curl -fsSL"

Once you have Homebrew, you can install gdb. If you’re using High Sierra (macOS  10.13), be aware that gdb 8.1 and 8.2 are not compatible. Instead, use gdb 8.0.1.

To install the latest version of gdb, run this command:

brew install gdb

You can install a specific version in this way:

brew install [email protected]

In case you already have a newer version of gdb, brew allows you switch version with the following command:

brew switch gdb 8.0.1

By running this command, you can find out your gdb version:

gdb --version

Take note of the version: you’ll need it later. In my case, it is 8.0.1.

Generate a certificate

Installing gdb is not enough. If you try debugging a file, you’ll get an error since the Darwin kernel doesn’t allow gdb to control another process without having special rights. For security reasons, this is the default behaviour.

To give gdb those permissions, you need to generate a certificate.

  1. Launch Keychain Access application: Applications > Utilities > Keychain Access.
  2. From the Keychains list on the left, right-click on the System item and select Unlock Keychain “System”.
  3. Go to Keychain Access > Certificate Assistant > Create a Certificate.
  4. Choose a name (e.g. gdb-cert).
  5. Set Identity Type to Self Signed Root.
  6. Set Certificate Type to Code Signing.
  7. Check the Let me override defaults check box.

At this point, you can go on with the installation process until you get the Specify a Location For The Certificate dialogue box. Here you need to set Keychain to System. Finally, you can click on the Create button.

After these steps, you can see the new certificate under System keychains. From the contextual menu of the newly created certificate (right-click on it) select the Get info option. In the dialogue box expand the Trust item and set Code signing to Always Trust.

Then, from the Keychains list on the left, right-click on the System item and select Lock Keychain “System”.

Finally, reboot your system.

Sign the certificate for gdb

It’s time to sign the certificate. Open your Terminal prompt and run:

codesign -s gdb-cert gdbPath

where gdb-cert is the name of your certificate and gdbPath is the full path to your gdb binary file. If you have installed gdb as explained before (using Homebrew), the path should be: /usr/local/Cellar/gdb/version/bin/gdb (replace version with the actual version of your gdb installation, e.g. 8.0.1).

Create a gdb command file

If you are on macOS Sierra (10.12) or later, you need to do this extra step.

In the home directory, create a new file called .gdbinit and write the following command in it:

set startup-with-shell off
view raw .gdbinit hosted with ❤ by GitHub

From the Terminal, you can do that by running this:

echo "set startup-with-shell off" >> ~/.gdbinit

Now you can use gdb for debugging files on your Mac. If you use Eclipse, follow the next step.

Set Eclipse for using gdb

If you want to configure gdb for a specific project in Eclipse, you need to set some options:

  1. Go to Run > Debug Configurations…
  2. Select a launch configuration from the list on the left (e.g. C/C++ Application)
  3. Open the Debugger tab from the menu on the right
  4. Set GDB debugger to the full path of your gdb binary file (the same used for signing the certificate)
  5. Set GDB command file to the full path of your .gdbinit file: ~/.gdbinit (or the extended form /Users/yourname/.gdbinit, where yourname is your username)
  6. Click on the Apply button.

Eclipse window for debug configurations

In case you want to define a default configuration for gdb to be used in any Eclipse project, these are the steps to follow:

  1. Go to Eclipse > Preferences
  2. From the left menu select C/C++ > Debug > GDB
  3. Set GDB debugger to the full path of your gdb binary file (the same used for signing the certificate)
  4. Set GDB command file to the full path of your .gdbinit file: ~/.gdbinit (or the extended form /Users/yourname/.gdbinit, where yourname is your username)
  5. Click on the Apply button.

Now, you can debug files from inside Eclipse using gdb.


In this tutorial, I’ve shown you how to install gdb and use it to debug a C/C++ application on macOS.

Special thanks to those people who helped me improve this article by commenting with suggestions and tips.


43 Replies to “How to setup gdb and Eclipse to debug C++ files on macOS Sierra”

  1. Do you have similar instructions for Mac OS 10.12.6? After I followed all your instructions here, gdb works okay on command line. However, when I run from eclipse, gdb complains that the work folder does not exist.
    : : No such file or directory.
    .gdbinit: No such file or directory.

    1. Hi, thanks for asking. I checked the process described in this article on macOS 10.12.6 and using both the two latest versions of Eclipse (Oxygen 1 and Neon 3). The sequence of steps to access the Eclipse debug configurations are slightly different (I updated this tutorial accordingly), but none that could have caused your problem.

      Have you verified that the .gdbinit file is actually in the path you set inside the Eclipse configurations? To do that, open a Terminal prompt, go to the home directory with

      cd ~

      (if you created the file inside this directory) and run the command

      ls -a .gdbinit

      If you get a result, the file does exist, otherwise you may have created it inside another directory.

      After this check, let me know if you still have problems with Eclipse.

    1. Hi!
      It may also be needful to reboot your Mac in Recovery mode (Restart and hold the CMR+R during restart). Then open the terminal and type the command “csrutil disable”. Then reboot again

  2. Make sure you UNLOCK system keychain before starting certificate assistant – this solved the problem I was getting wrt error code

    1. Good point, thanks for sharing! I updated the tutorial with a further step to unlock the System keychain before launching the Certificate Assistant and a step to lock it again after completing the process. Thank you for pointing that out!

  3. Great instructions. Thanks. I’ve just one issue. When trying to create the .gdbinit file, I got the following error message.

    You can’t use a name that begins with a dot “.”, because these names are reserved for the system. Please choose another name.

    I am on MacOs His Sierra (10.13.2). Can you tell me how to work around?

    1. Hello,

      you can create a file with a name starting with a dot in different ways.

      From the GUI, you can use names starting with a dot only if hidden files are shown. To show/hide hidden files you can use the shortcut cmd + shift + .

      From the Terminal, you can use whichever text editor (e.g. nano) you want without any restrictions on visibility.

  4. Hi , Thomas.

    Thanks for putting these instructions. I followed them , but still can’t run debug on Eclipse Oxygen.2. It says “Error in final launch sequence” and when I open Details I get :

    “Error in final launch sequence
    Failed to execute MI command:
    Error message from debugger back end:
    Unable to find Mach task port for process-id 651: (os/kern) failure (0x5).\n (please check gdb is codesigned – see taskgated(8))”

    I verified that gdb is codesigned :

    $ codesign -s gdb-cert /usr/local/Cellar/gdb/8.0.1/bin/gdb
    /usr/local/Cellar/gdb/8.0.1/bin/gdb: is already signed

    And .gdbinit file exists in my home directory :
    $ ls -a .gdbinit
    $ cat .gdbinit
    set startup-with-shell off

    What else could go wrong ?


  5. Thanks – there are many solutions out there, this is the one which worked for me. Important to set the .gdbinit path.

    1. These instructions (nor any other instructions) did not work for me on High Sierra. I was able to successfully run gdb via Eclipse by installing via Macports rather than Homebrew. The rest of the instructions were ok.

      1. Thanks a lot. I can confirm that on High Sierra 10.13.4, it worked by installing gdb via macports rather than homebrew and following the rest of the instructions as per.

        1. The tutorial is now updated considering some specific issues with High Sierra, like the non-compatibility with gdb 8.1.

          I guess that by using Macports you would get directly the gdb version compatible with High Sierra instead of the latest one.

    1. The tutorial is now updated considering some specific issues with High Sierra, like the non-compatibility with gdb 8.1.

    1. The tutorial is now updated considering some specific issues with High Sierra, like the non-compatibility with gdb 8.1.

  6. Got the same creation error message as joejoe even with the System keychain unlocked; this seems to be a known issue. Simply create the certificate in your session keychain and then drag & drop it into the System keychain.

  7. Get the following error (sierra 10.13.2), any idea how to fix ? seems to be an issue with all certs. Thx.

    $ codesign -fs gdb-cert /usr/local/bin/gdb
    error: The specified item could not be found in the keychain.

  8. A couple of comments (vis-a-vis High Sierra 10.13.5):

    You must be sure you are not running gdb 8.1 (at least not homebrew’s). You will need to downgrade to 8.0.1 — instructions can be found here:

    Some suggestions to improve the post:

    — in the “Set Eclipse to use GDB” section, it would be better for step 5 to recommend setting the path to .gdbinit as: ~/.gdbinit Then you aren’t dependent on knowing your correct short username.

    — even with eclipse Oxygen, I recommend taking the steps under “In case you are using an older version of Eclipse (Mars or previous)” since these steps make the gdb and gdbinit settings the default. Otherwise, you’ll need to reset the gdb and .gdbinit paths for each unique run config you generate.

    1. Thomas, can you add this information into your very helpful tutorial? It could save loads of time for everybody who works with High Sierra….

      1. Hi Elena, I’ve just updated my tutorial to also deal with High Sierra specific issues. Thanks for pointing that out and thanks to vtleslie for the valuable suggestion, I’ve appreciated it!

  9. Thomas, thank you SO much for your tutorial!

    Have been cracking my head trying to get Eclipse all set up to work in C++.
    Your instructions worked perfectly up until the .gdbinit file. I used Héctor Pérez’s tip in the comments to write it and it worked perfectly. Think my issue was I initially saved with some kind of extension.

    Running on High Sierra (10.13.6)

  10. Hello Thomas,

    Thanks for this set-up guide!

    I’m running El Captain (10.11.6) and when I start debugging, Eclipse (2018-09 (4.9.0)) says that it can’t check the version of GDB.
    gdb –version doesn’t work in terminal either.
    man gdb doesn’t give the option –version

    Would you have an idea which way to go?

    1. Hi Sjoerd,

      if you have gdb correctly installed, you should be able to see the version by starting it. Try running from the Terminal the command “gdb”. If it doesn’t start the debugger, then it’s not installed, at least not correctly.

  11. I have the same problem as Eugene (triying to debug in eclipse-> “Error in final launch sequence”) and tried different Solutions.
    None worked.
    Do u have any idea how to solve the problem?

  12. When I tried the above to use gdb 8.0.1 to debug a simple executable build by gcc (g++ -g TestProject.cpp -o test) , I got “not in executable format: File format not recognized”
    If I run the excutable directly, it runs fine.

    Any solution? Thanks.

    1. I have not found a solution to this either. It seems to have something to do with the architecture being compiled, and whether the version of gdb supports this. Given that I just created a default hello world program and followed the directions, it seems very odd that others have not also run into this problem. I’m on Mojave

      1. Dear Andrew Voelkel, me to work with macOS Mojave 10.14.4, and I had the same problem, but I change to a new WorkSpace and it compile y run successful. Here the message the test in Eclipse 2019-03 (4.11.0):

        09:01:05 **** Incremental Build of configuration Debug for project CppTest1 ****
        make all
        make: Nothing to be done for `all’.
        09:01:05 Build Finished. 0 errors, 0 warnings. (took 124ms)

  13. I’m wondering if anyone else has seen this problem.

    I Have Eclipse Photon 2018-09 (4.9.0) installed, the latest Xcode command line tools & installed gdb 8.0.1 via MacPorts. I’m running macOS 10.11.6. Debugging works fine in Eclipse EXCEPT, that complex (structures) Global variables don’t display properly in the Expressions tab. In the “Type” column, for all variables, it displays “”. This seems like a compiler issue (clang/gcc) not generating correct debug information. But in Eclipse, the C/C++ debug settings are configured to generate debug info.

    All local variables in the Variables tab are displayed properly. That is, the Type column displays the proper structure name & all the fields of the structure can be viewed using the disclosure triangles in the Name column.

    Any suggestions?

  14. I have the same problem as Jerron above. No one else is seeing this?? Surprising. I’m on Mojave. I checked the binary, it is 64 bit and not a fat binary.

Leave a Reply

Your email address will not be published. Required fields are marked *