Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.


xcgo is a maximalist Docker image for cross-compiling and releasing/distributing CGo-enabled Go/Golang applications. At this time, it can build and dist macOS, Windows and Linux CGo projects for arch amd64.

xcgo has what gophers crave:

  • go 1.17
  • OSX SDK Catalina / macOS 10.15 (will build on later versions)
  • docker
  • snapcraft
  • goreleaser
  • golangci-lint
  • mage
  • zsh
  • and a bunch of other stuff.

The primary source of documentation for xcgo is the wiki. Start there. There's a companion example project (neilotoole/sqlitr) that was created explicitly to exhibit xcgo: it demonstrates pretty much the entire array of xcgo's capabilities, showing how to release to brew, scoop, snap, Docker Hub, GitHub, etc. The neilotoole/xcgo images are published to Docker Hub.

Note: No effort has yet been made to provide support for other archs such as 386 (or for an OS beyond the typical three), but pull requests are welcome. Note also that no effort has been made to make this image slim. xcgo by mission is maximalist (it's a 3GB+ image), but I'm sure the Dockerfile can be slimmed down. Again, pull requests are welcome.


You can test xcgo with:

$ docker run -it neilotoole/xcgo:latest go version
go version go1.17.2 linux/amd64

To play around in the container, launch into a shell:

$ docker run -it neilotoole/xcgo:latest zsh

xcgo doesn't prescribe a particular usage approach. Some possibilities:

  • Launch a container shell session, clone your repo, and build (or even edit and do all your work) within the container.
  • Mount your local repo into the container, shell in, and build from within the container.
  • With local repo mounted, invoke xcgo with goreleaser: this is pretty typical.

Example: go build inside container

From inside the docker container, we'll build (amd64) binaries for macOS, Linux, and Windows.

Shell into the xcgo container if you haven't already done so:

$ docker run -it neilotoole/xcgo:latest zsh

From inside the container:

$ git clone && cd sqlitr
$ GOOS=darwin GOARCH=amd64 CC=o64-clang CXX=o64-clang++ go build -o dist/darwin_amd64/sqlitr
$ GOOS=linux GOARCH=amd64 go build -o dist/linux_amd64/sqlitr
$ GOOS=windows GOARCH=amd64 CC=x86_64-w64-mingw32-gcc CXX=x86_64-w64-mingw32-g++ go build -o dist/windows_amd64/sqlitr.exe

You should end up with something like this:

$ tree ./dist
├── darwin_amd64
│   └── sqlitr
├── linux_amd64
│   └── sqlitr
└── windows_amd64
    └── sqlitr.exe

Example: goreleaser

Quite possibly you'll want to use xcgo in conjunction with goreleaser.

Again, we'll use sqlitr to demonstrate. On your local machine, clone the sqlitr repo, mount it into the xcgo container and run goreleaser.

$ git clone && cd sqlitr
$ docker run --rm --privileged \
-v $(pwd):/go/src/ \
-v /var/run/docker.sock:/var/run/docker.sock \
-w /go/src/ \
neilotoole/xcgo:latest goreleaser --snapshot --rm-dist

The above will build that CGo project via goreleaser with binaries for macOS, Linux, and Windows.

$ tree ./dist
├── build_linux_linux_amd64
│   └── sqlitr
├── build_macos_darwin_amd64
│   └── sqlitr
├── build_windows_windows_amd64
│   └── sqlitr.exe
├── checksums.txt
├── config.yaml
├── goreleaserdocker393975300
│   ├── Dockerfile
│   ├── LICENSE
│   ├──
│   ├── sqlitr
│   └── testdata
│       └── example.sqlite
├── sqlitr_v0.1.23-snapshot_darwin_amd64.tar.gz
├── sqlitr_v0.1.23-snapshot_linux_amd64
│   └── prime
│       ├── meta
│       │   └── snap.yaml
│       └── sqlitr
├── sqlitr_v0.1.23-snapshot_linux_amd64.deb
├── sqlitr_v0.1.23-snapshot_linux_amd64.rpm
├── sqlitr_v0.1.23-snapshot_linux_amd64.snap
├── sqlitr_v0.1.23-snapshot_linux_amd64.tar.gz

Again, see the wiki for more.


Some params that can be passed to xcgo (as args to docker run):


    When present, xcgo's performs a docker login. Supply -e DOCKER_REGISTRY=X to use a registry other than Docker Hub.


    Used to publish artifacts to GitHub (e.g. by goreleaser).

  • Snapcraft: -v "${HOME}/.snapcraft.login":/.snapcraft.login

    When /.snapcraft.login is present in the xcgo container, performs a snapcraft login. This enables use of snapcraft, e.g. by goreleaser to publish a snap.

    Supply -e SNAPCRAFT_LOGIN_FILE=/other/place/.snapcraft.login to specify an alternative mount location for the login file. See the wiki for more.


First, consult the wiki and the neilotoole/sqlitr example project. Then open an issue.


See FAQ on wiki.

Related Projects

Comments for related projects are as of 2020-03-14: