Using Binary-Only Packages In Go

Shiju Varghese

When I provide consulting on Go to larger enterprises they’re often ask for a feature to distribute their Go packages as a binary-only packages without including the source code used for compiling the packages. I do understand that this feature is required for some enterprise organizations and also for commercial distribution of packages. Recently one organization told me that they are working on projects by leveraging various teams of different business units within the organization, where one team share the source to another team in binary form and don’t want to include the source code.

Go 1.7 adds an experimental feature to distribute packages in binary form without sharing the source code. To do this, you need to distribute the following files:

  1. Package binary for specific platforms.
  2. Include a source file not excluded by build constraints, and containing a “//go:binary-only-package” comment near the top of the file.

Note that binary only packages don’t work with “go get” command, thus you need to distribute the package as a zip file. The image below shows the directory structure of an example package that distributes as a binary-only package.

Directory structure of a binary-only package

Inside the directory binarypkg, we write source code for the package to compile into binary. Two sub-directories - pkg and src, are included for distributing the package in binary form. The pkg directory is used for providing the package binary and src directory is used for containing the source file with “//go:binary-only-package” comment. The command below from the directory binarypkg compiles the source and generates the output into pkg directory:

go build -o pkg/darwin_amd64/ -x

The package binary is generated to be used as the package name when it distributes to package consumers. Thus, we write a source file into the src/ directory inside the directory binarypkg, to include the “//go:binary-only-package” comment. Here is the entire source of the file to containing the “//go:binary-only-package” comment.

//go:binary-only-packagepackage binarypkg

Just including the “//go:binary-only-package” comment in a single source file, you don’t need to distribute the source code. The command below zip the src and pkg directories to distribute the binary-only package to package consumers:

zip -r src/* pkg/*

Since binary-only packages don’t work with “go get” command, you need to distribute it as a zip file by including the pkg directory that contains package binary and src directory that contains a source file with the “//go:binary-only-package” comment. The package consumers should copies the src and pkg directories to their GOPATH by extracting the zip file you distribute as binary-only package as shown below:

unzip -d $GOPATH/

When you compile a program that includes a binary-only package, the go command will refuse to recompile the package source if it found the “//go:binary-only-package” comment and will use the suitable binary form of the package.

You can see an example for a binary-only package at

You can follow me on twitter at @shijucv. I do provide training and consulting on Go programming language (Golang) and distributed systems architectures, in India.

Shiju Varghese

Written by

Distributed Systems Architect, Go Hacker and Author of two books on Go. Provides consulting and training on Go, Cloud-Native Microservices in India.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade