GRBL: The Complete Guide to the Open-Source CNC Controller

Last modified: November 19, 2026

Stylized text "grbl" in black sans-serif font with rounded edges on white background.

GRBL (pronounced "gerbil") is free, open-source firmware that turns an Arduino into a CNC motion controller. It reads G-code sent over USB and turns it into precisely timed step and direction pulses for your stepper motors. It runs most 3018-style desktop routers, a large share of diode laser engravers, and countless DIY machines, and it's what earlier Shapeoko and X-Carve controllers were built on.

This guide covers what GRBL does, what it can't do, how to install and set it up, and what to use when you outgrow it. For the details, see the companion pages:

GRBL at a Glance

What it is Firmware for the motion controller (not software you run on your PC)
Current version GRBL 1.1h, released August 2019
Runs on Arduino Uno, Nano, and other ATmega328P boards
Axes 3 (X, Y, Z); a dual-motor axis is a compile-time option
Connection USB serial at 115200 baud
Max step rate 30 kHz
License Free, open source (GPLv3)
Source github.com/gnea/grbl

What GRBL Does

A CNC machine needs three layers of software:

  1. CAD and CAM on your computer turn a design into toolpaths and write them out as G-code.
  2. A G-code sender on your computer (Universal Gcode Sender, gSender, Candle, LaserGRBL, and so on) streams that G-code to the controller and gives you jog buttons, a position readout, and a start button.
  3. The controller firmware, GRBL, runs on the Arduino. It parses each G-code line, plans the motion, and generates the step pulses that move the motors.

GRBL is only that third layer. It has no screen and no user interface of its own; everything you see on your computer belongs to the sender.

What makes GRBL good at its job:

Who Makes GRBL, and Is It Still Maintained?

GRBL was written by Simen Svale Skogsrud in Norway, and Sungeun "Sonny" Jeon has led development since. The official repository is gnea/grbl on GitHub (the older grbl/grbl repository holds the original project).

The last release, GRBL 1.1h, came out in August 2019. There hasn't been a new version since, because GRBL fills the 32 KB of flash on an ATmega328P almost completely; there's no room left for new features. Development moved to 32-bit successors that keep GRBL's G-code dialect and $ commands:

GRBL 1.1 is still a perfectly good controller for a 3-axis hobby router or laser. Pick grblHAL or FluidNC if you need more axes, more speed, a tool changer, or network control.

Machines and Boards That Run GRBL

Electronic circuit board with green, red, silver, and white components.

If you're building a DIY CNC machine, see our guides to CNC controllers, drivers, and boards and DIY CNC electronics.

Arduino Uno Pin Map (GRBL 1.1 Defaults)

If you're wiring a bare Arduino or checking a CNC shield, these are GRBL 1.1's default pins:

Function Uno pin
Step pulse X, Y, Z D2, D3, D4
Direction X, Y, Z D5, D6, D7
Stepper enable (all axes) D8
Limit switches X, Y, Z D9, D10, D12
Spindle PWM / enable D11
Spindle direction D13
Reset/abort, feed hold, cycle start A0, A1, A2
Coolant flood, mist A3, A4
Probe A5

GRBL 0.8 and earlier used D11 for the Z limit and D12 for spindle enable. GRBL 0.9 swapped them so spindle speed could use the hardware PWM on D11, which is why some older shields and wiring diagrams don't match.

How to Install GRBL on an Arduino

Skip this if your machine came with a controller board; it already has GRBL. To load it onto a blank Arduino Uno or Nano:

  1. Install the Arduino IDE.
  2. Download the source code ZIP from the gnea/grbl releases page and unzip it.
  3. In the Arduino IDE, choose Sketch > Include Library > Add .ZIP Library and select the grbl folder inside the unzipped folder (the one that contains config.h), not the top-level folder.
  4. Open File > Examples > grbl > grblUpload.
  5. Select your board and port under Tools, then click Upload. The upload sends the whole GRBL firmware, even though the sketch itself looks empty.

The releases page also has a ready-made .hex file you can flash with a tool such as XLoader or avrdude, which skips the IDE entirely. Either way you get the default build; to change compile-time options like dual-axis support or the homing order, edit config.h before uploading.

Uploading GRBL erases the board's settings. If you're reflashing a machine that already works, save the output of $$ first so you can put your settings back.

Connecting and Configuring GRBL

Connect with any G-code sender, or the Arduino IDE's Serial Monitor, at 115200 baud. GRBL greets you with:

Grbl 1.1h ['$' for help]

Type $$ and press Enter to list the settings. Change one by sending $ + number + = + value, for example $100=800. GRBL replies ok and saves the value to EEPROM, so it survives power cycles.

The settings you'll set up first on a new machine:

Setting What it sets
$100, $101, $102 Steps per mm for X, Y, Z. Get these right first; every distance depends on them.
$110 to $112 Maximum rate for each axis (also the G0 rapid speed), mm/min
$120 to $122 Acceleration for each axis, mm/sec²
$3 Reverses an axis that moves the wrong way
$22, $23 Enable homing, and which direction each axis homes
$20, $21, $130 to $132 Soft limits, hard limits, and maximum travel
$30, $31 Spindle RPM that maps to full and minimum PWM output
$32 Laser mode, for laser engravers only

Every setting, with defaults and tips, is on our GRBL settings page, along with a calculator for steps per mm from your motor, microstepping, and screw pitch or belt.

GRBL Commands You'll Use

Besides G-code, GRBL understands two kinds of commands of its own. The $ commands are typed as a line:

Command What it does
$$ List all settings
$x=value Change a setting
$H Run the homing cycle
$X Unlock after an alarm (use with care: GRBL may not know where the machine is)
$# Show work offsets (G54 to G59, G28, G30, G92), tool length offset, and the last probe result
$G Show the active G-code modes (units, distance mode, plane, WCS, and so on)
$I Show the version and build info
$C Check mode: GRBL parses G-code and reports errors without moving
$J=... Jog, for example $J=G91 X10 F500
$RST=$ Restore all settings to defaults ($RST=# clears offsets, $RST=* both)
$SLP Sleep mode (disables steppers and spindle until reset)

The realtime commands are single characters that act immediately, even in the middle of a job:

Key What it does
? Status report: state, position, feed, overrides
! Feed hold: decelerate and pause
~ Cycle start: resume after a feed hold or M0
Ctrl-X Soft reset (stops everything; may lose position if the machine was moving)

Your sender usually has buttons for all of these.

Supported G-codes in GRBL 1.1

GRBL supports the core of standard G-code. Everything below works; anything not listed is rejected with error:20 (unsupported command).

Group G-codes and M-codes
Motion G0, G1, G2, G3, G38.2 to G38.5 (probing), G80
Non-modal G4 (dwell), G10 L2, G10 L20, G28, G28.1, G30, G30.1, G53, G92, G92.1
Units, distance G20, G21, G90, G91, G91.1
Plane G17, G18, G19
Feed rate mode G93 (inverse time), G94 (units per minute)
Work coordinates G54 to G59
Tool length offset G43.1 (dynamic), G49
Cutter compensation G40 only
Path control G61
Program flow M0, M1, M2, M30
Spindle, coolant M3, M4, M5, M8, M9 (M7 mist is a compile-time option)

For what each code does, see our G-code and M-code list, G0 and G1, G2 and G3 arcs, and G54 work offsets.

GRBL's Limitations

GRBL packs a lot into an 8-bit chip, but there are things it can't do. Most "my program won't run" problems come from this list:

The fix for most of these is the post processor. Choose a GRBL post in your CAM program (Fusion, Vectric, Carbide Create, Estlcam and most others include one) and it will write G-code GRBL understands. Before you run a new program, preview it in a G-code viewer such as CutViewer to catch mistakes before they become crashes.

G-code Senders for GRBL

You need a sender on your computer to run GRBL. The most popular ones are free:

Machine makers often have their own: Carbide Motion for Shapeoko and Easel for X-Carve. For more options, see our free CNC software and CNC router software guides.

GRBL vs. Mach3, LinuxCNC, and Commercial Controls

GRBL Mach3 / Mach4 LinuxCNC grblHAL / FluidNC
Cost Free Paid license Free Free
Runs on An Arduino; any PC sends G-code over USB A Windows PC plus a motion controller A dedicated Linux PC A 32-bit board; USB, network or SD card
Axes 3 6 9 6 or more
Canned cycles, cutter comp, macros No Yes Yes Partial
Best for Hobby routers and lasers Hobby and light production mills and routers Retrofits, complex machines Bigger hobby machines, upgrades from GRBL

See our guide to choosing a CNC controller for the full comparison.

Troubleshooting GRBL

Frequently Asked Questions

What does GRBL stand for?

GRBL isn't an acronym. It's simply the project's name, pronounced "gerbil". You'll sometimes see expansions such as "G-code Reference Block Library", but those were made up after the fact.

Is GRBL the same as G-code?

No. G-code is the language a CNC program is written in. GRBL is the firmware that reads G-code and turns it into motor movements. GRBL understands a subset of standard G-code plus its own $ commands for settings and control.

Is GRBL still maintained?

GRBL's last release, 1.1h, came out in August 2019, and the original 8-bit version is essentially finished because it has run out of memory on the ATmega328P. Development continues in its 32-bit successors, grblHAL and FluidNC, which use the same G-code and $ commands.

What baud rate does GRBL use?

GRBL 1.1 uses 115200 baud (8 data bits, no parity, 1 stop bit). GRBL 0.8 and earlier used 9600.

Can GRBL control a 4th axis?

Not the standard GRBL 1.1 build on an Arduino Uno, which handles X, Y and Z. It can drive two motors on one axis (a dual-motor gantry) as a compile-time option. For a rotary 4th axis, use grblHAL or FluidNC.

How do I unlock GRBL after an alarm?

Find and fix whatever caused the alarm first. Then either run the homing cycle with $H, which is the safe choice because it re-establishes the machine's position, or send $X to clear the lock without homing. Our alarm code list explains each alarm.

What's the difference between GRBL and LaserGRBL?

GRBL is the firmware on the controller board. LaserGRBL is a free Windows program that sends G-code to a GRBL board, with tools for converting images into laser engraving jobs. LaserGRBL needs GRBL on the machine to work.

Does GRBL support tool changes?

GRBL doesn't support M6 or automatic tool changers. Most senders handle a tool change by pausing the job so you can swap the tool and reset Z, either with a probe or by touching off by hand. grblHAL adds real tool change support.

Be the first to know about updates at CNC Cookbook

Join our newsletter to get updates on what's next at CNC Cookbook.