Pages Menu
Categories Menu

Posted by on Jun 14, 2015 in Atmel AVR, Microcontrollers | 23 comments

Setting up AVR-GCC Toolchain on Linux and Mac OS X

Setting up AVR-GCC Toolchain on Linux and Mac OS X

Windows users have been enjoying various awesome tools to help with their AVR development process like the Atmel Studio, Codevision AVR, WinAVR, IAR Embedded Workbench, etc. This doesn’t mean that Mac and Linux users are at any unfair advantage. The avr-gcc toolchain supports Unix based OS like Linux and Mac OS X inherently.

In this post I will show how to install the avr-gcc toolchain and avrdude on Mac OS X and Linux. If you are using a Mac and want to save the trouble of going through these steps, simply install CrossPack for AVR Development and follow the instructions in the manual. I might go over it sometime in future though.

However if you really want to learn how to set up a cross-compiler, write Makefiles and use command line tools to get things done, I highly recommend doing the following steps. And trust me, they are pretty straightforward.

Step 1: Install Homebrew (Mac OS X only)
Step 2: Install avr-gcc toolchain
Step 3: Install avrdude
Step 4: Test the toolchain

Busy and just want to get s#!t done? Read the summary!

Step 1: Install Homebrew (Mac OS X only)

This step is not required for Linux users since almost all Linux distribution comes with a package manager.

Homebrew is the new super-awesome package manager for Mac OS X. Install it by typing (or pasting) the following in terminal:

ruby -e "$(curl -fsSL"

Step 2: Install avr-gcc toolchain

Mac OS X

First tap the repository:

brew tap osx-cross/avr

Then install the latest version of avr-libc (version 4.9.2 at the time of writing):

brew install avr-libc

This will pull avr-binutils and avr-gcc along with it as well. The second steps takes a little while to install everything, so go get yourself some tea in the meantime.

The Homebrew repository doesn’t has the avr-gdb formulae yet. If you need the avr-gdb debugger, go for the AVR CrossPack.


The following steps are for Debian/Ubuntu Linux. For other Linux distributions, please install read this.

It is usually a good idea to update all the packages you already have installed.

sudo apt-get update
sudo apt-get upgrade all

Then install the required packages.

sudo apt-get install gcc-avr binutils-avr avr-libc

You can also install gdb-avr is you like. It is useful for in-system debugging/emulation.

sudo apt-get install gdb-avr

Once done, type avr- in the terminal and press tab twice (do not hit enter). You should be able to see all the tools installed for you.

avr-gcc tools installed on Mac

avr-gcc tools installed on Mac

Step 3: Install avrdude

AVR-GCC is a toolchain that will help you with the software development process, but doesn’t do anything about burning the final executable (the hex file) to the microcontroller. For that we need to install AVR Downloader UploaDEr (avrdude).

Mac OS X

We will again use Homebrew to install it.

brew install avrdude --with-usb


The following steps are for Debian/Ubuntu Linux. For other Linux distributions, please install read this.

sudo apt-get install avrdude

This should be pretty quick. Once installed, type avrdude -v in the terminal to check if it is installed properly.

Step 4: Test the toolchain

That’s all we need for now. Let’s test whether it works or not. I have used the LED blinking code called led.c for ATmega32 for demonstration. Refer to this post to understand what it does.

Once the tools are installed no matter how, everything from here remains the same for both Mac OS X and Linux.

#ifndef F_CPU
#define F_CPU 16000000UL // or whatever may be your frequency

#include <avr/io.h>
#include <util/delay.h>                // for _delay_ms()

int main(void)
    DDRC = 0x01;                       // initialize port C
        // LED on
        PORTC = 0b00000001;            // PC0 = High = Vcc
        _delay_ms(500);                // wait 500 milliseconds

        //LED off
        PORTC = 0b00000000;            // PC0 = Low = 0v
        _delay_ms(500);                // wait 500 milliseconds

Assuming the name of the file is led.c, type the following in the terminal and check if the led.hex file is generated or not. The code should compile without any errors. Don’t worry if you don’t understand what the commands do or mean, we will discuss about them in detail in the next post.

avr-gcc -g -Os -mmcu=atmega32 -c led.c
avr-gcc -g -mmcu=atmega32 -o led.elf led.o
avr-objcopy -j .text -j .data -O ihex led.elf led.hex

Type cat led.hex in the terminal and see if the hex file is generated. If you see something like in the image below, you’re all set! :)

Final Hex FileWe will need the hardware to test avrdude, so let’s just skip it for now. In my next post, I’ll show you how you can use the avrdude to transfer the hex file generated above to run on an actual hardware. If you have any questions, please ask them below. Thank you.


Here’s what you gotta do on Mac OS X:

ruby -e "$(curl -fsSL"
brew tap osx-cross/avr
brew install avr-libc
brew install avrdude --with-usb

And here’s what you gotta do on Debian/Ubuntu Linux:

sudo apt-get install gcc-avr binutils-avr gdb-avr avr-libc avrdude

For all other Linux distributions, read this.

Thanks for reading! Subscribe and stay updated!

Written by Mayank Prasad
Last updated on June 14, 2015


  1. I dislike installing software already present.
    Install Arduino would be the better option, it is just an editor with two buttons that invoke avr tool chain. Go turn verbose on for the build and upload phases in the preferences.txt file (linked in the Arduino preferences tab, edit it outside of opened Arduino as it locks the file, reopen Arduino after changes). The tool chain is under the contents (this is of course Mac OS X , where you right click the app and show the packages contents). Export a path to the avr bin area (ie for the terminal .bash_profile file, you need to enable showing .dotfiles using a command I cannot recall).

    I can put a perl script that I am building to duplicate what the Arduino IDE does (with macs editor). I have replaced all the full paths with variables and have summarised the build and upload commands, arguments, and upload send receive messages.

  2. Hey! Thanks for this instruction! The latest Arduino IDE updates annoyed me that much so I was looking for ways to compile without. Worked like a charm :-)

    • Awesome! :)

  3. Thank you, exactly what I was looking for!

    • Cool :D

  4. Helped me a lot. Thank you!

  5. No avr and avr-libc in homebrew as of 2016.1.9.

    • Really? Were you able to install it yet?

    • Make sure you first tap the repo where the avr formulae exist:

      brew tap osx-cross/avr

      Then you’ll be able to install the toolchain using:

      brew install avr-libc

  6. Thanks for the quick and easy setup on Mac.

  7. Thank you Max for the post.

    I have some problems with building elf file on my Mac (on linux it works great).

    When I have tried to build avr-gcc -g -Os -mmcu=atmega32 -c led.c I got:

    main.c:3:20: fatal error: avr/io.h: No such file or directory

    So I added include path to avr/io.h (avr-gcc -g -Os -mmcu=atmega32 -I/usr/local/Cellar/avr-libc/1.8.1/avr/include -L/usr/local/Cellar/avr-libc/1.8.1/avr/lib -c led.c) and I manage to build object-file for led.o.

    But then problems with elf file started (avr-gcc -g -Os -mmcu=atmega32 -I/usr/local/Cellar/avr-libc/1.8.1/avr/include -o led.elf led.o) generate:

    /usr/local/opt/avr-binutils/bin/avr-ld: cannot find crtm32.o: No such file or directory
    /usr/local/opt/avr-binutils/bin/avr-ld: cannot find -lm
    /usr/local/opt/avr-binutils/bin/avr-ld: cannot find -lc
    collect2: error: ld returned 1 exit status

    So I added library path to avr-gcc (avr-gcc -g -Os -mmcu=atmega32 -I/usr/local/Cellar/avr-libc/1.8.1/avr/include -L/usr/local/Cellar/avr-libc/1.8.1/avr/lib -o led.elf led.o), but I still have problems:
    /usr/local/opt/avr-binutils/bin/avr-ld: cannot find crtm32.o: No such file or directory
    collect2: error: ld returned 1 exit status

    I even added path’s to include and lib to my environment, but without any success ;/

    There’s some problem with path’s, but I runout of idea’s…


    • Are you sure you installed the toolchain right?

  8. Thanks for the great simplified tutorial for installation of avr-gcc
    Waiting for your “next” post with avr-dude

    • It’s coming. :)

  9. Thanks a lot. I’m a rookie in Linux. This helped me a lot. Hope we’ll get to see th ‘next’ post soon. :)

  10. Is there a way I can use an avrdude patch on the MacOSx AVRDUDE?
    There is an issue with the USBTiny programmer and I need to install a patch in order for AVRDUDE to work as I’d like.
    Let me know, Thanks!

    • I am not aware of the issue with USBTiny. I also don’t know how to patch it. There should be instructions along with the patch on how to do it.

  11. Hi, avr-gcc stoped working on mac OS X 10.11.4, do you know hoy to fix it?

    • What’s the error that it’s showing?

  12. hi max
    thanks for the awesome post .
    i have a question , in this script :

    avr-objcopy -j .text -j .data -O ihex led.elf led.hex

    you have used .text which i can not find any description about .text using –help on avr-objcopy like i couldn’t do the same for ihex , could you please explain more about the script and how did you find you should work with .text

    thanks a lot

    • The elf file that is generated usually has text and data sections. Text section is the program code that you wrote. Data section is the initialized global/static variable. Sometimes you have a bss section as well, which is basically all the uninitialized variables. ihex means that the output file will be in Intel Hex format.

    • Thanks for sharing Phonesavanh! Appreciate it! :)

Leave a Reply

%d bloggers like this: