Easily Create Your First MPLAB Project: Step-by-Step Guide

An MPLAB project is the organized set of source files, configuration settings, libraries, and build rules you use inside the MPLAB X Integrated Development Environment to build firmware. This guide shows beginners how to create an MPLAB project, compile example code, and run a simple MPLAB LED blink code exercise using both XC8 and AVR-GCC toolchains.

Table of Contents

Quick Answer: How to Create a New MPLAB Project

To create a new MPLAB project in MPLAB X IDE, select File → New Project from the top menu. Next, choose the device (an AVR 8-bit MCU) and USB programmer, select the compiler toolchain (MPLAB XC8 or AVR-GCC), name the project, and select the project location. Finally add or create source files. That new MPLAB project is then ready to build and program. Continue reading for step-by-step detailed instructions.

Setting up the MPLAB X Integrated Development Environment

Before creating a project:

Install MPLAB X IDE from Microchip and the appropriate compiler (MPLAB X IDE with XC8 or AVR-GCC).
Confirm your programmer/debugger (e.g., PICkit, Atmel-ICE) is supported.
Open MPLAB X and verify Tools → Options → Embedded shows the compiler path under the Build Tools tab.

This environment lets you manage MPLAB example projects and run MPLAB code examples quickly.

Step-by-step: How to Create a New Project in MPLAB X IDE

The following are the basic steps to making a new project in the MPLAB X IDE. More details of each step follow.

Open the MPLAB X IDE.
File → New Project → Microchip Embedded → Application Project(s).
Select your device (e.g., ATmega328P).
Choose a tool (programmer/debugger/evaluation kit) or Simulator.
Select the compiler: MPLAB XC8 or AVR-GCC.
Name the project and choose location.
Add existing files or create a new source file (main.c).
Write the C application code.
Build and program.

This sequence creates a functional MPLAB project in minutes. Each step is included in detail below.

Open the MPLAB X IDE

Before starting, install the MPLAB X IDE if you have not already done so. Start the MPLAB X IDE after installation and configuration. Once the IDE is started, plug in the evaluation kit that you have. The IDE recognizes the evaluation kit and opens a page for it. For example, the Microchip AVR64EA48 Curiosity Nano evaluation kit is plugged into the computer USB port and the following page opens in the IDE, as shown in the image below. This is just an example, use any compatible AVR 8-bit evaluation kit or board that you would like to use.

When using a custom board, breadboard circuit or similar with an external programmer, plug in the programmer and power up the circuit or board.

Create a New MPLAB Project

In the IDE, select File → New Project… from the top menu, or click the New Project… button on the top toolbar, or use the keyboard shortcut Ctrl + Shift + N. This opens the New Project dialog box as the following image shows.

For a normal C code project, such as a ‘Hello, world!’, or blinking LED project, leave the default settings. That is, the selected category is Microchip Embedded and the projects item selected is Application Project(s). Click the Next button to continue project setup.

Select Your Device and Tool

When using a Microchip evaluation kit, the correct device is automatically selected in the next dialog box. This is assuming that the evaluation kit is plugged into the USB port. If the programming tool is not selected in the Tool field, then manually select it there. There is the option of selecting No Tool, Simulator, or the built-in programmer on the evaluation kit. The dialog box with the AVR64EA48 Curiosity Nano evaluation kit example is shown below. Click the Next button to continue.

If using a custom board, breadboard circuit, or similar with an external programmer, manually select the correct Device that is on the board. Use the Family field to narrow down the options in the device field if needed. Afterwards, select the tool that you are using to program the device in the Tool field. Click the Next button to continue.

Select a Compiler

In the next dialog box a list of installed compiler toolchains is shown. Click the one you wish to use. It may be necessary to expand one of the items to see the compiler to select. The following image shows the two compiler toolchains installed on the computer in use. The first is the Microchip XC8 compiler, and the second is the AVR-GCC compiler. In this example, the XC8 compiler is selected as shown in the image below. Click the Next button after selecting the desired compiler toolchain.

Name the Project and Choose a Location

In the final new project dialog box, name the project and choose the location to save it to. The default location is in the user’s home folder in a sub-folder called MPLABXProjects that was created by the MPLAB X IDE. I usually make a sub folder in this folder to put my project. For example a sub folder called avr64ea48-cnano for the AVR64EA48 Curiosity Nano evaluation kit. The following image shows the new project name as blink-xc8. In addition the image shows that this project is created in /home/user/MPLABXProjects/avr64ea48-cnano. Click the Finish button when ready.

Note that the project is created in a new sub-folder of the selected folder. In this example the project is in a folder called blink-xc8.X in the avr64ea48-cnano folder.

Create a New Source File

In the left pane of the IDE under the Projects tab right-click the Source Files item and then select New → main.c… from the pop-up menu. Name the new file main and leave the extension as c, as the following image shows. Click the Finish button when ready. As a result, a new main.c file is added to the project with some default skeleton code.

Write the C Application Code

In this example a C blink application is written that blinks the on-board LED of the AVR64EA48 Curiosity Nano evaluation kit. Before starting to write the code, find out which pin the on-board LED is attached to on your board or circuit. On the AVR64EA48 Curiosity Nano evaluation kit this is pin PB3. Look in the circuit diagram or user guide for your board to find the correct LED pin. The following code blinks or flashes the on-board LED (LED0) on the AVR64EA48 Curiosity Nano evaluation kit.

#define _XTAL_FREQ 3300000UL        // 3.3 MHz default on Curiosity Nano
#include <xc.h>


void main(void) {
    
    VPORTB.DIR |= PIN3_bm;          // Set pin PB3 as output for LED0

    while (1) {
        VPORTB.OUT &= ~PIN3_bm;     // Switch LED on (active low)
        __builtin_avr_delay_cycles(_XTAL_FREQ/2); // 0.5 s delay
        VPORTB.OUT |= PIN3_bm;      // Switch LED off
        __builtin_avr_delay_cycles(_XTAL_FREQ/2); // 0.5 s delay
    }
}

Copy

#define _XTAL_FREQ 3300000UL        // 3.3 MHz default on Curiosity Nano
#include <xc.h>


void main(void) {
    
    VPORTB.DIR |= PIN3_bm;          // Set pin PB3 as output for LED0

    while (1) {
        VPORTB.OUT &= ~PIN3_bm;     // Switch LED on (active low)
        __builtin_avr_delay_cycles(_XTAL_FREQ/2); // 0.5 s delay
        VPORTB.OUT |= PIN3_bm;      // Switch LED off
        __builtin_avr_delay_cycles(_XTAL_FREQ/2); // 0.5 s delay
    }
}

Build and Program

After entering the program code, click the Build for Debug Main Project button on the top toolbar. Hover the mouse cursor over the buttons on the toolbar to bring up the tooltip text for each button to find out what they are.

With no compile time errors in the code, upload the program to the target board. Click the Run Main Project toolbar button which uploads the code to the board. For the above code, LED0 on the AVR64EA48-CNANO board blinks or flashes at 1Hz with a 50% duty cycle.

MPLAB Code Examples You Can Try

Use these quick examples to verify your setup:

MPLAB LED blink code (XC8): a single-file main.c that toggles a port pin with a delay. The previous code is an example of this, as well as a similar example that follows.
MPLAB AVR-GCC example code: uses functions in avr/io.h and util/delay.h to toggle pins. See the second code example that follows below.
MPLAB example projects: sample projects shipped with MPLAB X or provided on vendor pages for timers, ADC, and UART.

Example: MPLAB LED Blink Code (XC8)

The following example is similar to the previous code. It uses the bitwise exclusive OR to toggle the on-board LED0 on pin PB3 on and off. The difference is that they duty cycle is stuck at 50% in this code, whereas it can be changed in the previous code. It uses a delay function that the XC8 toolchain can link into the code.

This XC8 snippet is a typical MPLAB XC8 example code for blinking an LED.

// MPLAB XC8 example code — LED blink
#define _XTAL_FREQ 3300000UL        // 3.3 MHz default on Curiosity Nano
#include <xc.h>


void main(void) {
    
    VPORTB.DIR |= PIN3_bm;          // Set pin PB3 as output for LED0

    while (1) {
        VPORTB.OUT ^= PIN3_bm;      // Toggle LED
        __builtin_avr_delay_cycles(_XTAL_FREQ); // 1 s delay
    }
}

Copy

// MPLAB XC8 example code — LED blink
#define _XTAL_FREQ 3300000UL        // 3.3 MHz default on Curiosity Nano
#include <xc.h>


void main(void) {
    
    VPORTB.DIR |= PIN3_bm;          // Set pin PB3 as output for LED0

    while (1) {
        VPORTB.OUT ^= PIN3_bm;      // Toggle LED
        __builtin_avr_delay_cycles(_XTAL_FREQ); // 1 s delay
    }
}

Example: MPLAB AVR-GCC Blink C Code

Create a new project for this example. Follow the previous steps, but choose the AVR-GCC compiler toolchain in the New Project dialog box, as the following image shows. Add a new main.c file as done before and add the code below. Modify it as necessary for your particular board.

The following code targets the AVR64EA48 Curiosity Nano evaluation kit again with its on-board LED0 on pin PB3. Use this when your MPLAB project targets AVR-GCC.

// MPLAB AVR-GCC example code — LED blink
#define F_CPU 3300000UL
#include <avr/io.h>
#include <util/delay.h>

int main(void) {
    VPORTB.DIR |= PIN3_bm;         // Set PB3 as output

    while (1) {
        VPORTB.OUT ^= PIN3_bm;    // Toggle the LED
        _delay_ms(2000);          // 2 s delay
    }
}

Copy

// MPLAB AVR-GCC example code — LED blink
#define F_CPU 3300000UL
#include <avr/io.h>
#include <util/delay.h>

int main(void) {
    VPORTB.DIR |= PIN3_bm;         // Set PB3 as output

    while (1) {
        VPORTB.OUT ^= PIN3_bm;    // Toggle the LED
        _delay_ms(2000);          // 2 s delay
    }
}

Build the project and then upload it to the target board as done in the previous instructions. The LED blinks or flashes on and off at a rate of four seconds. That is, the LED is on for 2 seconds and off for 2 seconds.

MPLAB Project Tips

Use the project properties to set include paths and linker flags early (File → Project Properties).
Keep source files organized in src/ and headers in inc/.
Use version control (Git) at project root to track changes.
For quick tests, use the Simulator before using real hardware.
When switching compilers (XC8 ↔ AVR-GCC), check startup files and linker scripts.

Did You Know?

MPLAB X IDE is based on the NetBeans platform and supports many toolchains.
Example projects often include Makefile-style build scripts under the hood.
MPLAB can import example code from Microchip’s libraries and device-specific packs, making it easy to start with real MPLAB example projects.

MPLAB Project Frequently Asked Questions

How do I choose between XC8 and AVR-GCC for my MPLAB project?

XC8 is Microchip’s compiler with vendor support and integrated features; AVR-GCC is open-source and widely used. Choose based on license, optimization needs, and library compatibility.

Where can I find MPLAB code examples?

Look in MPLAB X’s Window → MPLAB Discover, Microchip’s website, and device-specific software framework packs.

Can I import Arduino sketches into an MPLAB project?

You can adapt Arduino code, but you’ll need to replace Arduino APIs with AVR-GCC or XC8 equivalents and configure the linker/startup code.

Why won’t my MPLAB project build?

Common causes: wrong device selected, missing compiler path, incorrect include paths, or incompatible linker script. Check Output window for error details.

Is there an MPLAB LED blink code template?

Yes — many MPLAB example projects include an LED blink example; you can also create the simple blink code shown above.

Conclusion

An MPLAB project is the basic unit for developing firmware inside the MPLAB X Integrated Development Environment. Creating one is straightforward: select the device, choose a toolchain (MPLAB XC8 or AVR-GCC), add source files, and build.

Use the provided MPLAB code examples and the MPLAB LED blink code to validate your setup, and follow the tips to keep projects maintainable. With these steps you’ll be comfortable creating and expanding MPLAB projects for AVR development.