GRBL stores its configuration as numbered $ settings: steps per mm, speeds, acceleration, homing, limits, spindle and laser. This page explains every setting in GRBL 1.1, gives the defaults, and has a steps per mm calculator for setting up a new machine.
New to GRBL? Start with our GRBL guide. If GRBL is showing an alarm or error number, see the GRBL alarm and error codes.
How to View and Change GRBL Settings
Connect to GRBL with your G-code sender's console or any serial terminal at 115200 baud.
- View all settings: type
$$and press Enter. - Change a setting: send
$+ number +=+ value, for example$100=800. GRBL answersok. - Settings are permanent. They're saved in the Arduino's EEPROM and survive power-off. Reflashing GRBL resets them, so copy the output of
$$into a text file before you change anything or update the firmware. - Restore the defaults:
$RST=$puts every setting back to the values the firmware was compiled with.
GRBL 1.1 lists settings as bare numbers ($100=250.000) without descriptions, to save memory. Most senders, including Universal Gcode Sender and gSender, have a settings screen that shows the names for you.
GRBL Settings Quick Reference
Defaults are for the standard GRBL 1.1 build. Machines that ship with GRBL usually come with their own values already set, so check yours with $$ before changing anything.
| Setting | Name | Units | Default |
|---|---|---|---|
$0 |
Step pulse time | microseconds | 10 |
$1 |
Step idle delay | milliseconds | 25 |
$2 |
Step pulse invert | mask | 0 |
$3 |
Step direction invert | mask | 0 |
$4 |
Invert step enable pin | on/off | 0 |
$5 |
Invert limit pins | on/off | 0 |
$6 |
Invert probe pin | on/off | 0 |
$10 |
Status report options | mask | 1 |
$11 |
Junction deviation | mm | 0.010 |
$12 |
Arc tolerance | mm | 0.002 |
$13 |
Report in inches | on/off | 0 |
$20 |
Soft limits enable | on/off | 0 |
$21 |
Hard limits enable | on/off | 0 |
$22 |
Homing cycle enable | on/off | 0 |
$23 |
Homing direction invert | mask | 0 |
$24 |
Homing locate feed rate | mm/min | 25 |
$25 |
Homing search seek rate | mm/min | 500 |
$26 |
Homing switch debounce delay | milliseconds | 250 |
$27 |
Homing switch pull-off distance | mm | 1.000 |
$30 |
Maximum spindle speed | RPM | 1000 |
$31 |
Minimum spindle speed | RPM | 0 |
$32 |
Laser mode enable | on/off | 0 |
$100, $101, $102 |
X, Y, Z steps per mm | steps/mm | 250.000 |
$110, $111, $112 |
X, Y, Z maximum rate | mm/min | 500.000 |
$120, $121, $122 |
X, Y, Z acceleration | mm/sec² | 10.000 |
$130, $131, $132 |
X, Y, Z maximum travel | mm | 200.000 |
GRBL always stores settings in millimeters, even if you report positions in inches ($13=1) or program in inches with G20.
Axis Masks: $2, $3, $23
Settings marked "mask" pick one or more axes with a single number. Add up the values of the axes you want: X = 1, Y = 2, Z = 4.
| Value | Axes |
|---|---|
| 0 | None |
| 1 | X |
| 2 | Y |
| 3 | X and Y |
| 4 | Z |
| 5 | X and Z |
| 6 | Y and Z |
| 7 | X, Y and Z |
For example, to reverse the direction of the Y axis only, send $3=2. To reverse X and Z, send $3=5.
Steps per mm Calculator
Steps per mm ($100, $101, $102) is the most important setting in GRBL: it tells GRBL how many motor steps move each axis one millimeter. If it's wrong, every dimension you cut is wrong by the same percentage.
GRBL Steps per mm Calculator
$100=200.000Steps per mm = motor steps per rev × microsteps × reduction ÷ mm of travel per drive turn. Travel per turn is the screw lead (pitch × starts, or 25.4 ÷ TPI × starts), the belt pitch × pulley teeth, or π × module × pinion teeth for a rack. Use the microstepping your driver's DIP switches or jumpers are actually set to.
Some common combinations, worked out with the formula:
| Drive | Motor | Microstepping | Steps per mm |
|---|---|---|---|
| T8 lead screw, 8 mm lead (2 mm pitch, 4 starts) | 1.8° | 1/8 | 200 |
| 2 mm pitch lead screw, single start | 1.8° | 1/8 | 800 |
| 5 mm pitch ball screw (1605) | 1.8° | 1/8 | 320 |
| GT2 belt, 20-tooth pulley | 1.8° | 1/16 | 80 |
| GT2 belt, 20-tooth pulley | 1.8° | 1/8 | 40 |
| 1/2"-10 Acme screw (10 TPI) | 1.8° | 1/8 | 629.921 |
Per-Axis Settings: $100 to $132
$100, $101, $102: Steps per mm
Steps per mm = (motor steps per revolution × microsteps) ÷ mm of travel per motor revolution. Use the calculator above. Then check it: command a long move such as G91 G0 X100, measure how far the axis really went, and use the calculator's "Correct from a measurement" tab to fine-tune.
Higher microstepping gives smoother motion but needs more steps per mm, and GRBL can only send 30,000 steps per second. At 800 steps/mm, that caps the axis at 2,250 mm/min, so don't go above the microstepping you need.
$110, $111, $112: Maximum rate, mm/min
The fastest each axis can move. It's also the speed of G0 rapids. GRBL limits every move so no axis exceeds its own maximum, so you can set a slow Z separately from fast X and Y.
To find the right value, raise it in steps and test with a long rapid move (G0 X200, then back) until the motor stalls, then set it 10 to 20% below that. Stalling is noisy but won't hurt the motor.
$120, $121, $122: Acceleration, mm/sec²
How quickly each axis gets up to speed. Lower values are gentler; higher values make the machine reach full feed sooner, which matters on short moves and detailed 3D work. Tune it the same way as max rate: increase until the motor stalls or the machine shakes, then back off 10 to 20%. Heavy gantries need lower values than light ones.
$130, $131, $132: Maximum travel, mm
The usable travel of each axis, measured from the home position. GRBL uses these values for soft limits and to know how far to search for the switches when homing. They only matter if homing is enabled.
Limits and Homing: $20 to $27
$20: Soft limits
With $20=1, GRBL checks every move against the machine's travel ($130 to $132) before it runs. A move that would go past the edge stops the machine with ALARM:2, and the machine keeps its position. Soft limits only work if homing is enabled, because GRBL has to know where the machine is; trying to turn them on without homing gives error:10.
$21: Hard limits
With $21=1, triggering a limit switch stops all motion immediately and sets ALARM:1. Because the stop is sudden, the machine has probably lost position and should be re-homed. Wire normally-open switches between the limit pin and ground; for switches at both ends of an axis, wire them in parallel. If you get random limit alarms when the spindle starts, it's usually electrical noise; see our guide to electrical noise and grounding.
$22: Homing cycle
With $22=1, $H runs the homing cycle: GRBL moves each axis to its switch to find a repeatable zero position. By default it homes Z first to lift the tool clear, then X and Y together. When homing is enabled, GRBL starts up locked (in an alarm state) until you home.
$23: Homing direction invert (mask)
GRBL looks for the home switches in the positive direction by default. If a switch is at the negative end of an axis, set its bit (X=1, Y=2, Z=4). For switches at X-minus and Y-minus with Z at the top, that's $23=3.
$24 and $25: Homing feed and seek rates, mm/min
Homing first moves quickly toward each switch at the seek rate ($25), backs off, then approaches slowly at the feed rate ($24) to find the exact trigger point. A slow feed gives more repeatable homing; a seek rate that's too fast can slam into the switch.
$26: Homing debounce, milliseconds
A short pause to let a mechanical switch stop bouncing. The default of 250 is cautious; 5 to 25 ms works for most switches and makes homing faster.
$27: Homing pull-off, mm
After homing, GRBL backs off the switches by this distance so they aren't left triggered. If you get ALARM:8, the pull-off is too short to clear the switch; increase it.
Spindle and Laser: $30 to $32
$30 and $31: Maximum and minimum spindle speed, RPM
These map spindle speeds to GRBL's PWM output. $30 is the RPM that gives full output (5 V on the Arduino's spindle PWM pin); $31 is the RPM for the lowest output. GRBL scales everything in between. Set $30 to your spindle's real top speed so that S12000 in your program means 12,000 RPM.
For lasers, $30 is the S value for full power. Most laser setups use $30=1000, so S500 is half power; match whatever your laser software outputs.
$32: Laser mode
With $32=1, GRBL changes laser power on the fly through a string of G1, G2 and G3 moves without stopping. It also turns the laser off during G0 rapids. With it off (the right setting for a spindle), GRBL pauses at every speed change to let a spindle catch up. Turn it on only for lasers.
Step Signals: $0 to $6
These settings match GRBL's signals to your stepper drivers and switches. Most machines can leave them alone, except $3.
- $0, step pulse time (microseconds): how long each step pulse lasts. 10 is fine for most drivers. External drivers sometimes specify a longer minimum in their datasheet. The minimum is 3.
- $1, step idle delay (milliseconds): how long the motors stay powered after a move ends.
$1=255keeps them powered all the time, which stops a Z axis from dropping and keeps the motors from losing their position between moves. The motors run warmer. - $2, step pulse invert (mask): inverts the step signal for drivers that need it. Rarely needed.
- $3, direction invert (mask): reverses an axis. The easiest fix for an axis that moves the wrong way. See axis masks.
- $4, invert step enable: for drivers whose enable input works the opposite way.
- $5, invert limit pins: GRBL treats a limit pin pulled to ground as triggered, which suits normally-open switches wired to ground. For normally-closed switches wired to ground (less sensitive to noise, and a broken wire shows up as a triggered switch), set
$5=1. If you wire switches to +5 V instead of ground, you need external pull-down resistors. - $6, invert probe pin: set to 1 if your probe reads triggered when it isn't touching.
Reporting and Motion: $10 to $13
- $10, status report options:
$10=1reports machine position (MPos),$10=0reports work position (WPos), and adding 2 includes buffer usage. Leave it at what your sender expects; most want$10=1. - $11, junction deviation (mm): how fast GRBL takes corners between moves. Higher values corner faster but risk lost steps; lower values slow down in corners. The default 0.010 is a good starting point. Lowering it can help with jerky or rough corners.
- $12, arc tolerance (mm): GRBL cuts arcs as many short lines; this is how far the lines may stray from the true arc. The default 0.002 mm is far tighter than most hobby machines can cut.
- $13, report in inches:
$13=1reports positions and speeds in inches. Settings stay in millimeters.
Settings vs. Compile-Time Options
Some behavior can't be changed with a $ setting, only by editing config.h and reflashing. These include the homing order, homing a single axis, dual-motor axes, the M7 mist coolant output, and using the spindle direction pin as enable. If the setting you're looking for isn't in the list above, it's probably one of these. Our GRBL guide explains how to flash GRBL.
Frequently Asked Questions
How do I see my GRBL settings?
Connect to GRBL in your sender's console or a serial terminal at 115200 baud, type $$ and press Enter. GRBL lists every setting as $number=value.
How do I reset GRBL settings to the defaults?
Send $RST=$. It restores all $ settings to the values the firmware was built with. $RST=# clears the work coordinate offsets, and $RST=* clears both. Save your current settings first; a machine maker's custom values will be lost.
What should steps per mm be?
It depends on your motors, microstepping and drive: (motor steps per revolution × microsteps) ÷ mm of travel per revolution. A 1.8° motor at 1/8 microstepping on a T8 lead screw with 8 mm lead needs 200; on a GT2 belt with a 20-tooth pulley at 1/16 microstepping it needs 80. Use the calculator for your setup.
Why does my axis move the wrong way?
The motor direction is reversed for that axis. Set its bit in $3 (X=1, Y=2, Z=4; add the numbers for more than one axis), or swap one coil pair on the motor connector with the power off.
Do GRBL settings survive a power cycle?
Yes. Settings are stored in EEPROM and kept until you change them, restore the defaults, or reflash the firmware.
Why does GRBL say "error:9" when I try to move?
GRBL locks out G-code while it's in an alarm state. Home the machine with $H, or unlock it with $X. See the GRBL alarm and error codes for what caused the alarm.
Be the first to know about updates at CNC Cookbook
Join our newsletter to get updates on what's next at CNC Cookbook.