Air — Live Reload for Go Applications

Introduction

Air eliminates the tedious cycle of save-build-restart during Go development. Every time you save a .go file, Air detects the change, rebuilds your project, and restarts the binary automatically. This brings the instant feedback loop that JavaScript developers enjoy (via nodemon) to Go.

With over 23,000 GitHub stars, Air is the most popular live-reload tool for Go. It supports custom build commands, file exclusion patterns, colored log output, and proxy mode for web frameworks.

What Air Does

Air uses filesystem watching (fsnotify) to monitor your project directory. When .go files change, it runs your build command (go build), kills the old process, and starts the new binary. It handles debouncing (multiple rapid saves), build errors (shows errors without crashing), and file pattern matching.

Architecture Overview

[Source Files (.go)]
        |
   [Air Watcher (fsnotify)]
   Monitors file changes
   Debounces rapid saves
        |
   [Build Phase]
   go build -o ./tmp/main .
   Shows build errors in terminal
        |
   [Restart Phase]
   Kill old process
   Start new binary
   Forward signals (SIGINT, etc.)
        |
   [Running Application]
   Your Go server/app
   Repeat on next change

Self-Hosting & Configuration

# .air.toml — Air configuration
root = "."
tmp_dir = "tmp"

[build]
cmd = "go build -o ./tmp/main ."
bin = "tmp/main"
full_bin = "APP_ENV=dev ./tmp/main"
include_ext = ["go", "tpl", "tmpl", "html"]
exclude_dir = ["assets", "tmp", "vendor", "node_modules"]
exclude_regex = ["_test\\.go"]
delay = 1000  # milliseconds
stop_on_error = true
send_interrupt = true
kill_delay = 500

[log]
time = false
main_only = false

[color]
main = "magenta"
watcher = "cyan"
build = "yellow"
runner = "green"

[misc]
clean_on_exit = true

# Common usage patterns

# Watch and rebuild
air

# With specific config
air -c .air.prod.toml

# Docker usage
# Dockerfile.dev:
# FROM golang:1.22
# RUN go install github.com/air-verse/air@latest
# WORKDIR /app
# CMD ["air"]

Key Features

• Auto-Rebuild — rebuilds on .go file changes
• Auto-Restart — restarts the binary after successful build
• Build Errors — displays errors without crashing the watcher
• File Patterns — include/exclude files and directories
• Debouncing — configurable delay for rapid file saves
• Colored Output — color-coded log output for build/watch/run phases
• Signal Forwarding — graceful shutdown via SIGINT
• Docker Ready — works in Docker containers for development

Comparison with Similar Tools

FAQ

Q: Air vs go run with fswatch? A: Air is purpose-built for Go with build error handling, debouncing, and proper process management. Manual fswatch + go run lacks build error display, graceful shutdown, and configuration.

Q: Does Air work with Go modules? A: Yes. Air runs whatever build command you specify. The default "go build -o ./tmp/main ." works with Go modules out of the box.

Q: Can I use Air in production? A: No. Air is for development only. In production, build a static binary and run it directly. Air adds overhead from file watching and rebuilding.

Q: How do I use Air with Docker Compose? A: Mount your source code as a volume, install Air in the image, and use "air" as the command. Changes on the host trigger rebuilds inside the container.

Sources

• GitHub: https://github.com/air-verse/air
• Documentation: https://github.com/air-verse/air#readme
• Created by cosmtrek (now air-verse)
• License: GPL-3.0