wireguard-go: the Go tunnel that replaces ip link add wg0
Mirror only. Official repository is at https://git.zx2c4.com/wireguard-go
At a glance
- What is it?
- wireguard-go reimplements the WireGuard tunnel in userspace Go, and its own README tells Linux and Windows users to pick something else. That tension decides who should run it.
- Who is it for?
- Adopt wireguard-go when you need a userspace tunnel on macOS, FreeBSD or OpenBSD, or when you are embedding the WireGuard protocol in a Go program of your own and want wg(8) configuration to keep working. Do not adopt it on a Linux server or a standalone Windows host: the README itself points you at the kernel module, which is faster and better integrated, and at the Windows app that consumes wireguard-go as a module.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 22 days ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- WireGuard/wireguard-go4,523 ★ · +115
| Repository | 2026-09-23 | 2026-11-14 |
|---|---|---|
| WireGuard/wireguard-go | 4.4k | 4.5k |
115 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A userspace stand-in for a kernel module you do not have
The problem wireguard-go solves is narrow and structural. WireGuard normally arrives as a Linux kernel module, and the command you learn is `ip link add wg0 type wireguard`. On a platform with no such module, that command does not exist. wireguard-go fills the gap: it is the same protocol implemented in Go, running in a normal process with its own TUN device.
That framing matters because it explains the odd advice in the project docs. The README tells Linux users to install the kernel module instead, since it is faster and better integrated into the OS. It tells Windows users to use the more fully featured Windows app, which consumes wireguard-go as a module rather than a binary. The project is not competing with the kernel implementation on its home ground. It is the fallback, and a library.
Two details about the repository itself catch the eye. This GitHub repository is a mirror only; the official one sits at git.zx2c4.com/wireguard-go, and the module path in go.mod confirms it: `module golang.zx2c4.com/wireguard`. The last push recorded for that mirror was on 2026-10-24, it carries no GitHub releases, and it ships under the MIT licence with a 2017-2025 copyright line on WireGuard LLC.
Where the traffic actually goes: device, tun, conn, and a control socket
The top level layout tells you what the runtime is made of. The top-level directories are `conn/`, `device/`, `ipc/`, `ratelimiter/`, `replay/`, `rwcancel/`, `tai64n/`, `tests/` and `tun/`, alongside `main.go`, `main_windows.go` and `version.go`.
The control socket is the part worth understanding, because it doubles as the shutdown signal. Interfaces are not configured by passing a config file at startup. You create the interface, then configure it out of band with `wg(8)`, `ip(8)` or `ifconfig(8)` exactly as you would with the kernel module. The same interface name governs both.
go.mod requires `golang.org/x/crypto`, `golang.org/x/net`, `golang.org/x/sys`, `golang.zx2c4.com/wintun` and `gvisor.dev/gvisor`, and the module targets Go 1.23.1.
Creating and removing an interface, and why rm on the socket works
Creating an interface is one command. It creates the device and forks into the background:
$ wireguard-go wg0Removal has two paths, and the second one is the interesting detail. The ordinary route is `ip link del wg0`. If your system cannot remove interfaces directly, the README offers a different lever: the control socket file. Removing it makes wireguard-go shut down, because the socket is what the daemon watches for its lifecycle. The path in the documented command is `/var/run/wireguard/wg0.sock`.
If you want to watch what it does, pass the foreground flag and raise the log level:
$ wireguard-go -f wg0Set the environment variable `LOG_LEVEL=debug` for more logging. Neither of these changes how the tunnel behaves; they only change whether the process stays attached to your terminal and how much it says while running.
Building from source: git clone, make, and a version.go the Makefile rewrites
Building from source is the route the project gives, and it needs a recent Go installation:
$ git clone https://git.zx2c4.com/wireguard-go
$ cd wireguard-go
$ makeClone from the official host, not the mirror. The default all target runs the generate-version-and-build rule first, and that step is more than a wrapper. It takes the tag from git describe --dirty, synthesises a small Go file holding that tag as a Version constant, and compares it against the existing version.go. Only when the two differ does it overwrite the file and mark the index entry as assume-unchanged. The effect is that a dirty working tree still builds, and the string it embeds still reflects that state.
The build itself is one go build over the top-level and one-level-deep Go sources, which is why the target depends on wildcard patterns for both depths. Installing honours PREFIX, DESTDIR and BINDIR, defaulting to a binary under /usr, which matters for anyone packaging this for a distribution. There is also a plain test target that runs go test over every package, and a clean target that removes the binary.
The platform gaps: no sticky sockets, no fwmarks, and utun will not hold your name
Every platform paragraph in the README is a limitation with a driver name attached.
macOS runs on the utun driver. It has no sticky sockets yet, and fwmarks will not be supported because of Darwin limitations. utun also refuses arbitrary interface names: you must pass `utun[0-9]+` to name one yourself, or plain `utun` to let the kernel pick. If you choose the latter and the environment variable `WG_TUN_NAME_FILE` is defined, the name the kernel actually chose gets written into that file. Any tooling that assumes it can look up `wg0` on macOS has to read that file instead.
OpenBSD has the same tun naming restriction with tun in place of utun, and the same WG_TUN_NAME_FILE trick. FreeBSD has no sticky sockets, and maps fwmark onto SO_USER_COOKIE. On OpenBSD fwmark maps onto SO_RTABLE.
Sticky sockets are the recurring absence. A missing sticky socket means source address selection is not pinned the way some multi-homed or policy-routed setups need, so a deployment that depends on that behaviour has to be reworked rather than tuned.
How the Go tunnel differs from the kernel module and from boringtun
The kernel implementation runs inside the network stack, so there is no userspace data copy and no separate process to supervise. wireguard-go runs as an ordinary user-space program. The README states the kernel module is faster and better integrated on Linux, and that is the whole of the difference in approach: one is a syscall path, the other is a process.
The third comparison worth naming is against wireguard-tools, but that is not a rival implementation. `wg(8)` belongs to wireguard-tools, and the README says to use it to configure a running wireguard-go interface.
Where this is the wrong choice
Linux servers are the clearest misfit. The README directs you to the kernel module, and it is right to: you gain the in-kernel data path and drop the gvisor stack and the extra process. Choosing wireguard-go there buys nothing the module does not already give, and costs throughput.
Windows standalone is the second. The project points you at the Windows app that embeds it, so running the raw binary means missing whatever that app adds around it.
There is a licensing boundary worth stating plainly. Redistribution carries one obligation: the copyright notice and the permission notice have to travel with every copy, and the software is granted with no warranty of any kind and no liability. That is a permissive grant with no service commitment behind it, so an operator running this in production is carrying the support burden alone.
Editorial conclusion
Adopt wireguard-go when you need a userspace tunnel on macOS, FreeBSD or OpenBSD, or when you are embedding the WireGuard protocol in a Go program of your own and want wg(8) configuration to keep working. Do not adopt it on a Linux server or a standalone Windows host: the README itself points you at the kernel module, which is faster and better integrated, and at the Windows app that consumes wireguard-go as a module. Before anything else, verify the tun driver on your target platform, because sticky sockets are missing on macOS, FreeBSD and OpenBSD, fwmarks are unavailable on Darwin, and an interface name like wg0 is simply not accepted by utun or tun. Check that your key management path can read the name out of WG_TUN_NAME_FILE before you build automation around a fixed interface name.
Frequently asked questions
What is wireguard-go?
It is an implementation of the WireGuard VPN written in Go, providing the tunnel in userspace where a kernel module is unavailable. Configuration is still done with wg(8), ip(8) or ifconfig(8) once the interface is running.
How do I install wireguard-go?
The documented route is to clone https://git.zx2c4.com/wireguard-go and run make, which needs the latest version of Go; the module targets Go 1.23.1. On Linux the README instead directs you to the kernel module installation page.
How do I use wireguard-go?
Run `wireguard-go wg0` to create an interface that forks into the background, then configure it with wg(8). Remove it with `ip link del wg0`, or delete /var/run/wireguard/wg0.sock where the system cannot remove interfaces directly, which shuts the process down.
Should I use wireguard-go or the WireGuard kernel module?
On Linux the README says to use the kernel module, because it is faster and better integrated into the OS. wireguard-go is the option for platforms without that module, such as macOS, FreeBSD and OpenBSD.
What is the difference between wireguard-go and wireguard-tools?
wireguard-tools is not an alternative implementation: wg(8) belongs to it, and wireguard-go is configured with wg(8). The distinction is between the configuration utilities and the daemon that carries the traffic.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 0 in the last 30 days; newest first.
- Go Implementation of WireGuardHacker News · Sep 13, 2026 · 5 points · 0 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/wireguard-wireguard-go)Star history chart for your README
[](https://hysenlabs.com/projects/wireguard-wireguard-go)Was this useful?