Installing GDB on OS X Mavericks

With its new OS release, Apple has discontinued the use of GDB in OS X. Since 2005 Apple has steadily been moving away from the GNU toolchain in favor of LLVM. This means that Xcode now uses LLDB instead.

LLDB looks to be a very nice replacement for GDB, and I hope to use it in the future, but currently Xcode is the only graphical front-end that supports its use; pretty much every other debugging GUI uses GDB under the hood, including Eclipse. So, if you want to debug C/C++ code in Eclipse CDT on the Mac, you must install GDB.1

Here is the procedure that worked for me.2 Others have reported issues with this, so please do let me know in the comments if it doesn't work for you.

Known Issues

GDB will not be able to breakpoint inside any template function, though it should be able to step into it. This problem may be resolved if you use the MacPorts installation procedure (below) but it may only work if you also compile with Apple's GCC.

It was also reported in the comments that it cannot breakpoint into a shared library function. I have not confirmed this issue myself.

Installing GDB

You can install via MacPorts or Homebrew. MacPorts has Apple's official GDB distribution, which is modified for OS X. This is probably the best option (thanks to CC's comment for this tip). However, on my machine this only seems to work if the program is compiled using Apple's GCC, which is no longer supported by Apple. All things being equal, I vastly prefer to avoid MacPorts altogether. So I installed with Homebrew, despite recommending MacPorts. If you have no preference either way, go with MacPorts.

Install with MacPorts

  1. Install Xcode and MacPorts, if not already installed.
  2. Now install the Apple GCC and GDB from MacPorts:
    $ sudo port install gdb-apple
    $ sudo port install apple-gcc42
  3. For the remainder of the tutorial, use /opt/local/bin/gdb-apple as the GDB executable
  4. Remember if you want breakpoints in template functions to work, you'll need to change your compiler to g++-apple-4.2 instead of g++! This can be done in your Makefiles or in your IDE settings.

Install with Homebrew

  1. Install Xcode and Homebrew, if not already installed.
  2. Now install GDB from Homebrew:
    $ brew tap homebrew/dupes
    $ brew install gdb
  3. For the remainder of the tutorial, use /usr/local/bin/gdb as the GDB executable

If that worked, then lucky you! Getting it compiled is where many people seem to have trouble. Now you just need to sign it to give it permission to control OS X processes.

Certifying GDB

Open up the Keychain Access application (/Applications/Utilities/Keychain Navigate via the menu to Keychain Access > Certificate Assistant > Create Certificate...


Enter a name for the certificate. For this how-to, I'll call it "gdb-cert". Set the fields exactly as shown below.


The maximum validity period is 999 days. I don't really want to deal with this again, so I'm going to max it out.


Keep clicking the "Continue" button until you are asked for a location. Set it to "System".3




Now make sure the cert is always trusted. Right-click the new certificate and select Get Info. Under the Trust section, set Code Signing to Always Trust.



Now that we have a certificate, we need to use it to sign GDB. First, we'll restart the taskgated process to make sure it picks up the new certificate. Quit Keychain Access (you must quit Keychain Access!) and return to the Terminal for these final commands.

Find the taskgated process.

$ ps -e | grep taskgated
56822 ??         0:03.11 /usr/libexec/taskgated -s
60944 ttys002    0:00.00 grep --color=auto taskgated

The first number in the above output is the PID. Use this to kill the process (it will immediately restart itself).

$ sudo kill -9 56822

Now you can finally code sign GDB.

# MacPorts version
$ codesign -s gdb-cert $(which gdb-apple)
# Homebrew version
$ codesign -s gdb-cert $(which gdb)

Now you should be all set! The OS X Keychain may ask for your password the first time you attempt to debug a program, but it should work!

Getting it to Work with Eclipse

There's one more step for Eclipse users. You need to specify where Eclipse can find the new GDB. Specify the path to GDB in Preferences > C/C++ > Debug > GDB:


If you already have some debug configurations, you may need to edit them individually to point to the correct place (under Run > Debug Configurations...):


  1. The CDT developers are planning to support LLDB, but they will have to write a whole new interface, and I think most of them only work on Eclipse in their spare time, so it will likely be at least some months before LLDB support is there.
  2. The procedure is derived from this StackOverflow post and this GDB Wiki page.
  3. If you are unable to save it to the System keychain, then save it to the login keychain. You can later export the cert, and then import it into the System keychain. I didn't have to do this, so comment if you have any problem.
Tagged , , , , , , . Bookmark the permalink.

55 Responses to Installing GDB on OS X Mavericks

  1. Kevin says:

    This was a huge help! Thanks for the detailed procedure.


  2. digitaurus says:

    Thanks for the article. I can't get breaks set for a shared library function to work. Have you encountered this problem ?

  3. ntraft says:

    Sorry, I haven't ever tried that, and am not in a position to at the moment. No one has mentioned that in the StackOverflow post either.

  4. Chul says:

    Thanks. This works perfectly for my Mavericks.

  5. fab says:

    Thanks. I have GDB working now. However, Eclipse allows me to debug but it doesn't allow me to set breakpoints anywhere inside templates functions. Have you guys experienced this before?

  6. ntraft says:

    Uh-oh. Yeah, I just checked, and it's happening to me too. That's a much more serious problem.

    It happens in raw gdb, not just Eclipse, so it's an issue with gdb somehow. It can step into template functions just fine, but not set breakpoints.

    I don't have a solution for this right now.

  7. luxward says:

    Help!!I just followed the step you listed.But I just got the this.
    ps -e | grep taskgated
    1282 ?? 0:00.03 /usr/libexec/taskgated -sp
    sudo kill -9 1282
    codesign -s gdb-cert /usr/local/bin/gdb
    gdb-cert: no identity found
    That is why?

  8. ntraft says:

    In the step where you created your certificate, what name did you give it? I named mine "gdb-cert", but you need to replace that with whatever name you chose.

  9. jl says:

    Hi, I have follow the steps, but when I try to debug some project, eclipse says: "'Launching 'project' has encountered a problem. Error with command: /usr/local/bin/gdb -- version"
    Do you have any idea why is this happening?
    Thank you

  10. ntraft says:

    It means it can't find your gdb. If you go to the terminal and run "/usr/local/bin/gdb --version" do you get some output? What is the result of running "which gdb"?

  11. Nidhi says:

    I followed your instructions to the letter but there were two problems:
    1) Under Preferences > C/C++ > Debug > there is no GDB option. Instead there is a GDB MI option, so I cant set the path there.
    2) I set the path to the debugger under Debug Configurations, but now when I run it on the Device I get the error :
    GdbServerReceiver: run-as: Package xxx is unknown
    NDK: Gdbserver not started properly
    NDK: Launch error: Failed to connect to remote VM

    How do i fix this?

  12. ntraft says:

    @Nidhi: It looks like you're trying to run a remote debugging session on an Android device? I have no experience with that. Seems like more of a problem with gdbserver than with gdb, though, judging from your error message.

  13. joeb says:

    i have it working when logged in directly on the machine but when i ssh into the machine remotely it says:

    Unable to find Mach task port for process-id 33493: (os/kern) failure (0x5).
    (please check gdb is codesigned - see taskgated(8))

    do i need to do something else for it to work on ssh/remote connections?

    any help greatly appreciated.

  14. ntraft says:

    @joeb: Whoa, that's pretty weird! Maybe it has something to do with the user you're logging in as... although I thought that codesigning should mean that any user can use it.

    As a temporary workaround, doing "sudo gdb" may work. Other than that, I got nothing for you. Do post back if you find an answer!

  15. Jordan says:

    I had the same problem as jl who posted:

    "Hi, I have follow the steps, but when I try to debug some project, eclipse says: "'Launching 'project' has encountered a problem. Error with command: /usr/local/bin/gdb -- version"
    Do you have any idea why is this happening?
    Thank you"

    So I followed your instructions:
    Your advice to enter 'which gdb' into the terminal resulted in "/usr/local/bin/gdb"

    When I run '/usr/local/bin/gdb --version', I get a lot of output related to gdb, which makes me think that I do have something there.

    However, I'm still encountering the result: "'Launching 'project' has encountered a problem. Error with command: /usr/local/bin/gdb -- version".

    What am I doing wrong?

  16. ntraft says:

    @Jordan: And you followed my instructions in the "Getting it to work in Eclipse" section? If so, then I'm not sure why it can't be accessed. Maybe it's a permissions issue.

  17. Oliver says:

    Thanks for this article! It helped me alot!
    But I had some problems, too! After following all instructions I got this error message:

    Unable to find Mach task port for process-id 33493: (os/kern) failure (0x5).
    (please check gdb is codesigned - see taskgated(8))

    The solution was NOT to change the settings from 'Getting it to Work with Eclipse'.
    Maybe it makes sense to try running gdb with eclipse first befor changing the settings.
    Thanks alot ntraft! :-)

  18. SoLuna says:

    I also had a same problem with above that error message.

    But, when i did "sudo gdb", it worked.

    thank you for this article.

  19. Manu says:

    Thanks a lot for this, saved a lot of time trying to google for the fix.

  20. M Ch says:

    great guide, thanks a lot

  21. CC says:

    I found a way to get this to work fully with the debugger. And this is the best tutorial I have found with the exception of using a gdb that isn't full feature. Thanks for putting this together!

    To get it to fully work you need to install the Apple version of gdb (gdb-apple) You can download it using Macports.

    First install Macports:

    Then install gdb-apple:
    sudo port install gdb-apple

    Then codesign it. I specified the new directory where it will be stored (/opt/local/bin/gdb-apple) in case you have already gone through this with the other version of gdb.
    codesign -s gdb-cert /opt/local/bin/gdb-apple

    You'll need to update the debug settings in Eclipse to reflect the change of location. And also restart eclipse after you make those location changes before debugging.

    Please update the main body of this tutorial to reflect this if you can. I've had to piece together three or four different tutorials to figure out how to finally get it to work. It took several hours of trial and error and lots of searching. Hoping someone else can confirm this works.

  22. ntraft says:

    Nice find, CC! I had assumed that MacPorts had all the same packages as Homebrew. I'll add that to my to-do list for this weekend!

  23. Anna says:

    Great guide, really, thank you!

  24. Emilio says:

    I followed your directions step by step. Everything is working well, and the Lazarus IDE now compiles and runs perfectly. Thanks a lot!

  25. ntraft says:

    Hey everyone,

    I finally tried CC's solution, and it didn't work. The Apple version has exactly the same problems with templates. YMMV.

    I'll update the post anyway to give an alternative.

  26. Shuai Wang says:

    Thanks for your blog! It helps me a lot.

    I follows the above steps. Now I am facing a problem: when I code sign the gdb-cert, the terminal will show that: this identity cannot be used for signing code.

  27. Shuai Wang says:

    I fixed it!

    The mistake I made is that: I didn't choose "Code Signing" when I apply the "Create Certificate".

    A really helpful blog!
    Thanks again!

  28. ZihYou Liao says:

    Hi !
    I already Xcode and Homebrew but step 2 has trouble display "command not found", please help me thank you !

  29. ntraft says:

    Ensure /usr/local/bin is on your PATH. If you don't know what that means, look up "PATH environment variable."

  30. Dimitar Nedev says:

    Awesome guide!
    Debugging in Eclipse - I've been missing this since I moved to programming in C (and on a Mac). You just made my day.
    Thank you!

  31. Minghung Chang says:

    Finally, this article helps me to debug my code with Mac.
    Thank you so much!!

  32. Geva says:

    It's not obvious when you try to type in the dialog box, but the Certificate Assistant in Keychain Access will actually let you set a validity of up to 20 years for a certificate. So you can type, say '7000' in the time limit field and really not have to worry about this again.

  33. Sheng says:

    Hello! Could you please give me a hand on how to use gdb inside Eclipse? It is working, but always says: "warning: `/var/folders/2d/nlf0cxgs2xjczyvpm5by9fbw0000gn/T/Chello-c758b8.o': can't open to read symbols: No such file or directory." THX a lot !!!!

  34. ntraft says:

    As long as it's working, that's the important thing! The Apple GDB prints out some errors for me, but the normal GDB doesn't. I ignore them.

  35. kwixson says:

    Thanks! Worked for me. I really appreciate the clear, step-by-step instruction. I had no problem following along. Got it working in Eclipse, though Code Blocks (aka C::B) is another matter...but that's a C::B thing. They don't have dev's for OS X and issues aren't being fixed.

  36. Eric says:

    Hi Neil,
    Just wanted to say thanks for posting this howto. Your step-by-step instructions made installing gdb and getting it to work in eclipse a breeze. Thank you! And good luck in achieving your goals to be a computer scientist. You will make a great one!

  37. Adrian says:

    I obtain that error some help?

    Error in final launch sequence
    Failed to execute MI command:

  38. Anonym says:

    Thanks for the detailed instructions. It's very easy to follow. Now I can get gdb up and running just fine.

    Hi Adrian, make sure you did the signing properly.

    Good luck!

  39. Peter says:

    Many thanks for this very helpful instruction. I missed the signing procedure first but now it works perfectly.

    Many regards, Peter

  40. Jose says:

    How do you set the path for the gdb debugger? i cannot make it work


  41. Jose says:

    I did a simple program and compiles and runs but it does not debug... I get this error message:

    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 13832: (os/kern) failure (0x5).
    Unable to find Mach task port for process-id 13832: (os/kern) failure (0x5).

    Can Someone help me please?

  42. Rajesh says:

    Hey, I also got the error "Unable to find Mach task port for process-id 33493: blah blah blah"

    and you know what?

    "sudo gdb" worked for me and i was able to debug my program
    Thanks for the tutorial

  43. Jon says:

    I'm getting stuck at the code signing part. I got the certificate all made up according to the instructions and I killed taskgated, but when I run codesign I get an error "/opt/local/bin/gdb-apple: code failed to satisfy specified code requirement(s)"

    Anyone know how to get it to sign it?

  44. Narimaan says:

    I just can't get this to work right for some reason. I followed this 100% to the letter, installed gdb, got it code signed, SEE that it's listed as installed in my list of ports installed, but for whatever reason, gdb isn't in /usr/local/bin/. Anyone with a similar problem, would appreciate the help, but I guess I'll have to get used to no debugging on Eclipse for a while :(

  45. ntraft says:

    @Narimaan: run the command `which gdb` to find out where it's installed. If you used MacPorts, then it's probably in /opt/local/bin. (if you installed gdb-apple, use `which gdb-apple`)

  46. Narimaan says:

    I just did that, found gdb-apple in the /opt/local/bin/, made sure that that was the path in Eclipse, but still get the standard error of:

    "Error with command: /usr/local/bin/gdb --version
    Cannot run program "/usr/local/bin/gdb": Unknown reason"

    That's a little confusing because it sounds like it's looking somewhere I know gdb isn't, i.e. not in "/usr/local/bin/", so is there someway I can specify installing gdb-apple (or just gdb, I don't really care at this point which one as long as it works) to /usr/local/bin? (If there is a way, Macports' guide isn't noob-friendly enough to make it very clear)

  47. ntraft says:

    Eclipse may have cached the location in your Run Configuration. But you're right, you can fix the problem either way by creating a symbolic link:
    $ ln -s /opt/local/bin/gdb-apple /usr/local/bin/gdb

  48. Narimaan says:

    Ok so I did that, that fixed that specific error. THEN it started saying it couldn't do it because it couldn't find the specific folder "Eclipse" in my documents (I named mine originally "Eclipse Projects"). So I went back, changed my workspace to be in a folder called "Eclipse", redid a simple program I've been using as a guinea pig for getting debug to work, and NOW the error is just flat out:

    "Error with command: gdb --version
    Cannot run program "gdb": Unknown reason"

    Yeah I've got nothing when all it says is "unknown reason", so yeah, if you or anyone knows that specific error ("specific" being used lightly here), I'd love input on it, otherwise don't bother yourselves with it, I've got to find a new platform for coding c++ anyways, seems macs don't get a long with the idea of coding (unless it's to make an iPhone or Mac app, in which Xcode is the farthest thing from noob-friendly).

  49. ntraft says:

    Except notice that now it says "gdb" instead of "/usr/local/bin/gdb", so it lost your preferences when you moved your workspace (you probably forgot to move the .metadata folder). Go back through the last section of my tutorial.

  50. ntraft says:

    It also seems worth noting that C++ and ObjC are unfortunately the worst possible languages for newbies, no matter what your development environment. So if you can avoid them, you should. Even a seasoned programmer like myself is filled with rage and angst by C++.

  51. Narimaan says:

    Hehe oh yeah no I kind of agree with you there, though C++ isn't really that difficult for me to get since the first real coding language I learned was Python and it's pretty similar with differences in just the exact terms. Plus I'm taking a required c++ class right now so I'm just trying to set up a workable IDE outside of school to work on projects with.

  52. Narimaan says:

    And HALLELUJAH I finally fixed it! The last error I got after re-declaring the path was this:

    "Error in final launch sequence
    Failed to execute MI command:
    -environment-cd "/Users/narimaanvalian/Documents/Eclipse/Sample Distance Program"
    Error message from debugger back end:
    /Users/[my username]/Documents/Eclipse/Sample: No such file or directory
    /Users/[my username]/Documents/Eclipse/Sample: No such file or directory"

    So I took the same rout, remade my workspace folder, RENAMED every single possible file, folder, or project to have "_" instead of spaces, and NOW it finally works! Kind of annoying how I can't have spaces in any names now but at least it works! :D

  53. Lena says:


    I have a similar problem with Jon, while running codesign, I get this error message:
    codesign -s gdb-cert /opt/local/bin/gdb-apple
    error: /Applications/ can't create output file: /opt/local/bin/gdb-apple.cstemp (Permission denied)
    /opt/local/bin/gdb-apple: the codesign_allocate helper tool cannot be found or used

    please help!

  54. Kiana Ali Khademi says:

    i followed the above steps but when i try to sign the certificate it told me that -s command not found .what should i do ?please help me .

  55. ntraft says:

    Did you type the command exactly as shown, without the '$' sign? Try `codesign -h` to see what commands are available.

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>