Air: Live Reload for Go Development, Now with an Entrypoint-First Config

What Air Solves and Who Needs It

Air is a command line utility that watches your Go source files and, on any change, rebuilds and restarts your application. It solves the repetitive cycle of manually stopping a running server, recompiling, and starting it again. The README is explicit that this tool has nothing to do with hot-deploy for production; it is purely for development. The target user is a Go developer who spends time iterating on a web service, CLI tool, or any long-running process and wants immediate feedback. The tool runs in your project root, watches for changes, and leaves you to focus on code. It is not a library or a framework; it is a standalone binary that wraps your build and run commands.

The Core Mechanism: Watch, Build, Run

Air works by watching the file system for changes in your project. When a change is detected, it runs a build command you specify, then executes the resulting binary. The configuration file, typically .air.toml, defines the build.cmd and build.entrypoint. The entrypoint is the key new form: it points at the binary generated by build.cmd and describes how to execute it. The value can be a string, just the executable, or an array of strings. When using an array, the first element is the executable, resolved relative to the root unless it lacks a path separator, in which case $PATH is searched. This replaces the older build.bin field, which the repository description marks as deprecated and scheduled for removal. The documentation states that the legacy build.bin field is deprecated, so you should prefer the entrypoint form. The watch mechanism also supports excluding subdirectories, and it can watch new directories after Air has started, which is useful for monorepos or projects that generate code into new folders.

Getting Running: Install and First Config

Installation is straightforward. With Go 1.25 or higher, the recommended method is go install github.com/air-verse/air@latest. You need to ensure your Go bin directory is in PATH, for example by exporting PATH="$PATH:$(go env GOPATH)/bin". Alternatively, you can install it as a project tool with go get -tool github.com/air-verse/air@latest and then invoke it with go tool air -v. Other methods include a shell script, Homebrew (brew install go-air), Scoop, mise, or a Docker image. Once installed, navigate to your project root and run air. It first looks for .air.toml in the current directory; if not found, it uses defaults. To generate a config file you can edit, run air init once, which writes .air.toml with default settings. Then run air again to pick it up. You can also specify a config file explicitly with air -c .air.toml. Runtime arguments for the built binary are passed after the air command, such as air server --port 8080, and you can separate air's own arguments with --.

Configuration Depth: Entrypoint, Env Files, and Watch Rules

The configuration goes beyond a simple build and run. You can overwrite specific config fields from the command line, which is useful for scripts. For example, air --build.cmd "go build -o bin/api cmd/run.go" --build.entrypoint "./bin/api" works without a config file. List arguments can be repeated, and values are appended in order, which is handy for generated command lines. The misc.startup_banner setting controls what Air prints at startup: leave it unset for the built-in ASCII banner, set it to an empty string to print nothing, or set custom text. Environment files can be loaded via --env_files, and there are platform-specific build overrides. The README also describes watch rules that run a command instead of rebuilding, which is useful for tasks like regenerating assets. There is a proxy feature to reload the browser automatically on static file changes, which is a different use case from pure Go code reload. The entrypoint form is the recommended way to specify the executable, and the deprecation of build.bin means any existing configs using that field will need updating.

Real Limitations and Failure Modes

Air has clear boundaries. It is not for production hot-deploy; the README states this directly. So if you are looking for zero-downtime deployment, this is the wrong tool. Another limitation is the deprecation of build.bin. If you have an existing .air.toml that uses build.bin, it will keep working for now, but the field will be removed in a future release. That means a migration path is required, and you must update your config to use build.entrypoint. The README also mentions a known issue under WSL when the bin path contains a single quote, which can cause errors. That is a specific environment constraint. Also, the tool relies on file watching, so if your build process generates files outside the watched directories, Air may not trigger a rebuild. The documentation does not describe a way to watch files outside the project root, so if your dependencies are in a separate directory, Air may miss changes.

Docker and Containerized Development

Air can be used inside Docker or Podman, which is useful for consistent development environments. The README points to the cosmtrek/air image on Docker Hub. There is a shell function for using Air in a container, and a Docker Compose section. The image likely contains Air and a Go toolchain, but the README does not give exact Dockerfile contents. The key point is that Air is designed to run inside a container, watching files mounted from the host. This works well for developers who prefer to keep their toolchain in a container. However, file watching in Docker on macOS or Windows can be slow due to filesystem sharing, though the README does not address this. The Docker approach also means you need to handle volume mounts for your source code. The documentation does not provide a specific docker run command in the cleaned section, so you would need to check the full README or the image documentation.

Maintenance and Upgrade Considerations

Air is actively maintained, with recent releases in August 2026, including v1.67.4. The project is not archived. The license is GPL-3.0, which has implications if you distribute modified versions of Air itself, but using Air as a development tool does not affect your application's license. The README does not mention a migration guide for the build.bin to entrypoint transition, so you will need to check the release notes or the example config file, air_example.toml, for the current format. The go install method requires Go 1.25 or higher, so if you are on an older Go version, you must use a different install method, such as the install.sh script or a package manager. The project also has a Docker image, which is a separate distribution channel. Upgrading Air is as simple as running go install again, but you should test your config after each upgrade, especially if you rely on deprecated fields.

Alternatives and How They Differ

A common alternative is reflex, a file watcher that can run arbitrary commands. Reflex is language-agnostic: you define a pattern and a command, and it runs that command on changes. Air is Go-specific in that it has built-in knowledge of Go build and run, plus features like .env loading and platform-specific overrides. Another alternative is nodemon, which is Node-centric but can be configured for Go via a command. The difference is that Air is designed for Go's build toolchain, so it integrates with go build and go run directly, whereas reflex and nodemon are generic. In practice, if you only need to restart a process on file changes, a generic watcher might suffice. But Air's config structure, with build.cmd and build.entrypoint, is tailored to Go's compilation model. The deprecation of build.bin is a sign that the project is evolving its config to be more explicit about how the binary is executed, which is a difference from generic watchers that just run a shell command.

Editorial conclusion

Adopt Air if you write Go applications and want a zero-config watcher that rebuilds and restarts on file changes; it suits local development, not production hot-deploy. Skip it if you need production reload or if your project relies on the deprecated build.bin field, which will break in a future release. Before adopting, verify your Go version is 1.25 or higher for the recommended install, check that your config uses build.entrypoint instead of build.bin, and test how Air behaves with your specific build commands, especially if you use WSL or need to exclude directories.

Official sources

1. Official README
2. Project repository
3. Release notes