Air

Definition

Air is a live-reload command-line tool for Go application development that watches a project's source files and automatically rebuilds and restarts the compiled binary whenever a change is detected. It fills a gap created by Go being a compiled language, where a normal edit-run cycle otherwise requires manually stopping, recompiling, and relaunching the program after every change. Air is used during local development to shorten the feedback loop for building web servers, CLI tools, and other Go applications.

Overview

Air addresses a friction point specific to compiled languages: interpreted-language web frameworks can reload code changes into a running process almost instantly, while a Go program must be recompiled into a new binary before the change takes effect, which historically meant a manual stop-build-run cycle after every edit during development. Air automates that cycle so a developer can save a file and see the effect of a change without leaving their editor to run commands by hand. Mechanically, Air runs as a background process that uses file-system watching to detect changes within a configured set of directories and file extensions, typically Go source files and any templates or configuration a project specifies. When a change is detected, Air triggers a build using the project's own `go build` command (or a custom build command defined in its configuration file, typically named `.air.toml`), and if the build succeeds, Air stops the previously running process and starts the freshly built binary in its place, forwarding its standard output and error streams to the terminal. If a build fails, Air surfaces the compiler error directly rather than restarting a stale binary, which keeps the feedback tight even when a change introduces a syntax error. Air occupies a narrow, specific role compared to full frameworks like Buffalo, which includes its own live-reload command (`buffalo dev`) as one feature among many; Air is a standalone tool that any Go project can adopt regardless of which framework or router it uses, making it a common companion to minimal setups built on Gin, Echo, Chi, or plain `net/http`. It differs from language-level hot-reloading found in some other ecosystems in that Air always performs a full restart of the process rather than patching running code, since Go's compilation model does not support partial in-process reloading of arbitrary code changes. In practice, Air is added to a Go project as a development-only dependency, configured through a small TOML file specifying build commands, watched paths, and excluded directories such as vendor or test data, and then invoked in place of `go run` during local development. It is commonly used alongside Docker Compose setups, where Air runs inside a development container and rebuilds the service each time a mounted source file changes on the host machine. Because Air performs a full process restart rather than in-memory reloading, any in-memory application state is lost on every reload, which is an acceptable trade-off during API development but can be inconvenient when testing flows that depend on accumulated state, such as an in-progress WebSocket session; teams working on that kind of feature sometimes fall back to manual restarts or add persistence for state they need to survive a reload.

Key Features

• Watches Go source files and rebuilds automatically on change
• Restarts the compiled binary after a successful build
• Surfaces compiler errors directly instead of running a stale binary
• Configured through a simple .air.toml configuration file
• Supports custom build commands beyond plain go build
• Framework-agnostic, usable with any Go web library or CLI tool
• Commonly run inside Docker Compose development containers

Use Cases

Alternatives

Frequently Asked Questions

Related in Web