Skip to content
Get packs

Guide · Open source

How to use Wails: build desktop apps with Go and web tech

Updated · written with AI from the project's own documentation and checked against our catalogue data

Wails is an open-source framework for building desktop applications with Go for the backend and standard web technologies (HTML, JavaScript and CSS) for the interface. This guide explains what Wails does, how to install its CLI, which version to choose and what you can build with it. After reading, you will know whether Wails fits your Go project and where to start.

Wailswailsapp/wails · ★ 36.9k · MIT

Quick start

  1. 1Check prerequisites. Install Go, since Wails is written in Go and the CLI is installed with the Go toolchain.
  2. 2Pick a version. Choose v2 for the stable line listed in the README or v3.0.0 for the newer CLI.
  3. 3Install the CLI. Run the go install command for your chosen version from the install section.
  4. 4Create a project. Use the Wails CLI to generate a new project, optionally from a pre-built template.
  5. 5Write backend logic in Go. Add your application logic in Go and expose methods you want to call from JavaScript.
  6. 6Build the binary. Compile and bundle the project with the CLI to produce a single desktop binary.

What Wails does and how it works

The traditional way to give a Go program a web interface is a built-in web server. Wails takes a different approach: it wraps Go code and a web frontend into a single binary. The framework also handles project creation, compilation and bundling.

The README states that Wails uses native rendering engines rather than an embedded browser.

  • Backend logic is written in standard Go.
  • The interface uses HTML, JavaScript and CSS, and you can use any frontend technology you already know.
  • Go methods can be called from JavaScript.
  • Go structs and methods get auto-generated TypeScript definitions.

Install the Wails CLI

Wails is installed with the Go toolchain, so Go is the prerequisite. The README lists two active versions. v2 is marked stable, and v3.0.0 is also listed as stable with its own CLI. Pick one before you install.

Install the v2 CLI with the command below, or use the v3.0.0 command in the next line if you want the newer line. Full installation instructions are on the v2 and v3 documentation sites linked from the README.

  • v2 docs: v2.wails.io
  • v3 docs: wails.io
go install github.com/wailsapp/wails/v2/cmd/wails@latest go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0

Create, build and bundle your first app

Wails provides a CLI tool to quickly generate and build projects. It also offers pre-built templates for creating rich frontends for Go programs. Use the CLI to create a project from a template, then compile and bundle it into a desktop binary.

The exact subcommands and flags depend on the version you installed, so check the documentation for that version rather than relying on memory.

  • Choose a pre-built template to start with a working frontend.
  • Edit Go code for backend logic and the web files for the interface.
  • Build the project with the CLI to produce a single binary.

Use native dialogs, menus and window features

Wails includes native dialogs and menus, so your app can use operating-system UI elements instead of web imitations. It also supports native dark and light mode and translucency or frosted window effects.

Events move data between Go and JavaScript through a unified eventing system, which lets the two sides react to each other.

  • Native dialogs and menus
  • Native dark and light mode
  • Translucent and frosted window effects
  • Unified eventing between Go and JavaScript

Choose between v2 and v3

The README lists v2 as the stable line. It also lists v3.0.0 as stable, but the project's own analysis notes that v3 has no release binaries and that its version status is still settling. If you need a mature ecosystem today, v2 is the safer choice.

New functionality and public behaviour changes go through a Wails Enhancement Proposal (WEP), submitted as a draft pull request. The roadmap is in the project's GitHub discussions.

  • Use v2 if you want the line the README marks as stable with the most established ecosystem.
  • Consider v3 if you are comfortable with an evolving version and want its newer CLI, wails3.

What people use it for

  • Adding a web-style interface to an existing Go command-line or backend program.
  • Building a lightweight desktop tool in Go with HTML, CSS and JavaScript.
  • Making a desktop app with a React, Vue, Svelte or Angular frontend and a Go backend.
  • Shipping a Go program as one packaged binary that includes its interface.

Frequently asked questions

Is Wails free to use?

Yes. Wails is open source under the MIT licence, as listed in the project details. You can check the LICENSE file in the repository for the full terms.

What do I need before installing Wails?

You need Go installed. The Wails CLI is installed with the go install command, so you will also need a working Go setup.

Is Wails an alternative to Electron?

The project describes it as a lightweight Electron alternative for Go programmers. It uses native rendering engines rather than an embedded browser and offers native menus and dialogs. Electron is built for JavaScript and Node, so the right choice depends on your language.

Should I use Wails v2 or v3?

The README lists v2 as stable. v3.0.0 is also listed but has no release binaries, and its version status is still settling, so v2 is the more conservative option today.

Can I use Wails if I don't know Go?

No. The backend is written in Go, so you need Go programming skills. If you only want a web frontend with no Go, Wails is not the right tool.

How does Wails compare to Tauri, Fyne or Lorca?

The source lists these as comparable projects but does not compare them in detail. Wails is aimed at Go developers who want an HTML, JavaScript and CSS interface, so check each project's documentation against your needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Wails suits Go programmers who want a desktop app with a web-style interface, or who want to add a frontend to an existing Go program. Skip it if you do not know Go, need a browser-based web server, or want a settled v3 ecosystem.

Install options & downloads