---
title: go_binary
description: Build a Go command with a managed SDK.
---

# `go_binary`

`go_binary` builds one Go source file or one package directory with the selected managed SDK. It registers the build as a root task and returns its dependency.

## Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `entry_point` | Yes | Project-relative Go source file or package directory passed to `go build`. |
| `deps` | No | Dependencies activated before the build, in list order. Defaults to `[]`. |
| `output` | No | Project-relative output file. Defaults to `.xx/out/<entrypoint-name>`. |
| `flags` | No | String arguments inserted after `go build` and before xx's output and entrypoint arguments. Defaults to `[]`. |

The selected SDK is implicit; do not add `go` to `deps`. A source file uses its filename without extension for the default output. A package directory uses its directory name, while `entry_point="."` uses the project directory name. Windows adds `.exe` to default and custom outputs unless the name already ends with `.exe`, case-insensitively. xx creates missing parent directories.

Use `output` rather than `-o` or `--o` in `flags`. Entrypoints and outputs must remain inside the project after symlinks are resolved. Outputs cannot replace entrypoints, name directories, or overlap another active output.

## Examples

### Build one source file

```python
load("@go@1.26.5", "go_binary")

go_binary(entry_point="main.go")
```

This writes `.xx/out/main`, or `.xx/out/main.exe` on Windows.

### Build a package to a chosen path

```python
load("@go@1.26.5", "go_binary")

go_binary(
    entry_point="cmd/server",
    output="bin/server",
)
```

### Build a reproducible static binary

```python
load("@go@1.26.5", "go_binary")
load("@os@1", "env_set")

go_binary(
    entry_point="cmd/server",
    output="dist/server",
    flags=["-trimpath", "-ldflags=-s -w"],
    deps=[env_set("CGO_ENABLED", "0")],
)
```

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/examples/zig.md
Title: Zig Examples
Description: Direct Zig commands and Go CGO builds with a managed Zig distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/packages/go/go.md
Title: go
Description: Activate a managed Go SDK for dependent tasks.

URL: https://withxx.dev/packages/go/go_binary.md
Title: go_binary
Description: Build a Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_install.md
Title: go_install
Description: Install a versioned Go command for dependent tasks.

URL: https://withxx.dev/packages/go/go_run.md
Title: go_run
Description: Run a versioned Go command with a managed SDK.

URL: https://withxx.dev/packages/go/go_test.md
Title: go_test
Description: Test Go packages with a managed SDK.

URL: https://withxx.dev/packages/nodejs/nodejs.md
Title: nodejs
Description: Activate managed Node.js for dependent tasks.

URL: https://withxx.dev/packages/nodejs/npm_install.md
Title: npm_install
Description: Install project dependencies with managed npm.

URL: https://withxx.dev/packages/nodejs/npm_run.md
Title: npm_run
Description: Run a project package script with managed npm.

URL: https://withxx.dev/packages/nodejs/npx_run.md
Title: npx_run
Description: Run a versioned npm package command with managed npx.

URL: https://withxx.dev/packages/os/env_append.md
Title: env_append
Description: Append an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_get.md
Title: env_get
Description: Read a value from a task environment while evaluating Starlark.

URL: https://withxx.dev/packages/os/env_prepend.md
Title: env_prepend
Description: Prepend an item to a list-like environment variable.

URL: https://withxx.dev/packages/os/env_set.md
Title: env_set
Description: Set an environment variable for dependent tasks.

URL: https://withxx.dev/packages/os/env_unset.md
Title: env_unset
Description: Remove an environment variable from dependent tasks.

URL: https://withxx.dev/packages/os/run.md
Title: run
Description: Run a command from the project root.

URL: https://withxx.dev/packages/zig/zig.md
Title: zig
Description: Activate managed Zig for dependent tasks.

URL: https://withxx.dev/packages/zig/zig_cc.md
Title: zig_cc
Description: Configure managed Zig as a C and C++ compiler.

URL: https://withxx.dev/packages.md
Title: Built-in Packages
Description: Versioned toolchains, commands, and task environment helpers provided by xx.
-->