Build from source
Requirements
sing-box 1.11
- Go 1.23.1 - ~
sing-box 1.10
- Go 1.20.0 - ~
sing-box 1.9
- Go 1.18.5 - 1.22.x
- Go 1.20.0 - 1.22.x with tag
with_quic, orwith_utlsenabled
Simple Build
Or build and install binary to $GOBIN:
Custom Build
or
Build Tags
| Build Tag | Enabled by default | Description |
|---|---|---|
with_quic |
Build with QUIC support, see QUIC and HTTP3 DNS transports, Naive inbound, Hysteria Inbound, Hysteria Outbound and V2Ray Transport#QUIC. | |
with_grpc |
️ | Build with standard gRPC support, see V2Ray Transport#gRPC. |
with_dhcp |
Build with DHCP support, see DHCP DNS transport. | |
with_wireguard |
Build with WireGuard support, see WireGuard outbound. | |
with_utls |
Build with uTLS support for TLS outbound, see TLS. | |
with_acme |
Build with ACME TLS certificate issuer support, see TLS. | |
with_clash_api |
Build with Clash API support, see Experimental. | |
with_v2ray_api |
️ | Build with V2Ray API support, see Experimental. |
with_gvisor |
Build with gVisor support, see Tun inbound and WireGuard outbound. | |
with_embedded_tor (CGO required) |
️ | Build with embedded Tor support, see Tor outbound. |
with_tailscale |
Build with Tailscale support, see Tailscale endpoint. | |
with_ccm |
Build with Claude Code Multiplexer service support. | |
with_ocm |
Build with OpenAI Codex Multiplexer service support. | |
with_naive_outbound |
Build with NaiveProxy outbound support, see NaiveProxy outbound. | |
badlinkname |
Enable go:linkname access to internal standard library functions. Required because the Go standard library does not expose many low-level APIs needed by this project, and reimplementing them externally is impractical. Used for kTLS (kernel TLS offload) and raw TLS record manipulation. |
|
tfogo_checklinkname0 |
Companion to badlinkname. Go 1.23+ enforces go:linkname restrictions via the linker; this tag signals the build uses -checklinkname=0 to bypass that enforcement. |
It is not recommended to change the default build tag list unless you really know what you are adding.
Linker Flags
The following -ldflags are used in official builds:
| Flag | Description |
|---|---|
-X 'internal/godebug.defaultGODEBUG=multipathtcp=0' |
Go 1.24 enabled Multipath TCP for listeners by default (multipathtcp=2). This may cause errors on low-level sockets, and sing-box has its own MPTCP control (tcp_multi_path option). This flag disables the Go default. |
-checklinkname=0 |
Go 1.23+ linker rejects unauthorized go:linkname usage. This flag disables the check, required together with the badlinkname build tag. |
For Downstream Packagers
The default build tag lists and linker flags are available as files in the repository for downstream packagers to reference directly:
| File | Description |
|---|---|
release/DEFAULT_BUILD_TAGS |
Default for Linux (common architectures), Darwin, and Android. |
release/DEFAULT_BUILD_TAGS_WINDOWS |
Default for Windows (includes with_purego). |
release/DEFAULT_BUILD_TAGS_OTHERS |
Default for other platforms (no with_naive_outbound). |
release/LDFLAGS |
Required linker flags (see above). |
with_naive_outbound
NaiveProxy outbound requires special build configurations depending on your target platform.
Supported Platforms
| Platform | Architectures | Mode | Requirements |
|---|---|---|---|
| Linux | amd64, arm64 | purego | None (library included in official releases) |
| Linux | 386, amd64, arm, arm64 | CGO | Chromium toolchain, glibc >= 2.31 at runtime |
| Linux (musl) | 386, amd64, arm, arm64 | CGO | Chromium toolchain |
| Windows | amd64, arm64 | purego | None (library included in official releases) |
| Apple platforms | * | CGO | Xcode |
| Android | * | CGO | Android NDK |
Windows
Use with_purego tag.
For official releases, libcronet.dll is included in the archive. For self-built binaries, download from cronet-go releases and place in the same directory as sing-box.exe or in a directory listed in PATH.
Linux (purego, amd64/arm64 only)
Use with_purego tag.
For official releases, libcronet.so is included in the archive. For self-built binaries, download from cronet-go releases and place in the same directory as sing-box binary or in system library path.
Linux (CGO)
See cronet-go.
- glibc build: Requires glibc >= 2.31 at runtime
- musl build: Use
with_musltag, statically linked, no runtime requirements
Apple platforms / Android
See cronet-go.