Huge news!Announcing our $20M Series A led by Andreessen Horowitz.Learn more
Log inDemoInstall

Package Overview
File Explorer

Package XGB provides the X Go Binding, which is a low-level API to communicate with the core X protocol and many of the X extensions. It is *very* closely modeled on XCB, so that experience with XCB (or xpyb) is easily translatable to XGB. That is, it uses the same cookie/reply model and is thread safe. There are otherwise no major differences (in the API). Most uses of XGB typically fall under the realm of window manager and GUI kit development, but other applications (like pagers, panels, tilers, etc.) may also require XGB. Moreover, it is a near certainty that if you need to work with X, xgbutil will be of great use to you as well: This is an extremely terse example that demonstrates how to connect to X, create a window, listen to StructureNotify events and Key{Press,Release} events, map the window, and print out all events received. An example with accompanying documentation can be found in examples/create-window. This is another small example that shows how to query Xinerama for geometry information of each active head. Accompanying documentation for this example can be found in examples/xinerama. XGB can benefit greatly from parallelism due to its concurrent design. For evidence of this claim, please see the benchmarks in xproto/xproto_test.go. xproto/xproto_test.go contains a number of contrived tests that stress particular corners of XGB that I presume could be problem areas. Namely: requests with no replies, requests with replies, checked errors, unchecked errors, sequence number wrapping, cookie buffer flushing (i.e., forcing a round trip every N requests made that don't have a reply), getting/setting properties and creating a window and listening to StructureNotify events. Both XCB and xpyb use the same Python module (xcbgen) for a code generator. XGB (before this fork) used the same code generator as well, but in my attempt to add support for more extensions, I found the code generator extremely difficult to work with. Therefore, I re-wrote the code generator in Go. It can be found in its own sub-package, xgbgen, of xgb. My design of xgbgen includes a rough consideration that it could be used for other languages. I am reasonably confident that the core X protocol is in full working form. I've also tested the Xinerama and RandR extensions sparingly. Many of the other existing extensions have Go source generated (and are compilable) and are included in this package, but I am currently unsure of their status. They *should* work. XKB is the only extension that intentionally does not work, although I suspect that GLX also does not work (however, there is Go source code for GLX that compiles, unlike XKB). I don't currently have any intention of getting XKB working, due to its complexity and my current mental incapacity to test it.


Version published


XGB is the X Go Binding, which is a low-level API to communicate with the core X protocol and many of the X extensions. It is closely modeled after XCB and xpyb.

It is thread safe and gets immediate improvement from parallelism when GOMAXPROCS > 1. (See the benchmarks in xproto/xproto_test.go for evidence.)

Please see doc.go for more info.

Note that unless you know you need XGB, you can probably make your life easier by using a slightly higher level library: xgbutil.

This is a fork of

Quick Usage

go get go run go/path/src/

jezek's Fork

I've forked the XGB repository from BurntSushi's github to apply some patches which caused panics and memory leaks upon close and tests were added, to test multiple server close scenarios.

BurntSushi's Fork

I've forked the XGB repository from Google Code due to inactivty upstream.

Godoc documentation can be found here:

Much of the code has been rewritten in an effort to support thread safety and multiple extensions. Namely, has been thrown away in favor of an xgbgen package.

The biggest parts that haven't been rewritten by me are the connection and authentication handshakes. They're inherently messy, and there's really no reason to re-work them. The rest of XGB has been completely rewritten.

I like to release my code under the WTFPL, but since I'm starting with someone else's work, I'm leaving the original license/contributor/author information in tact.

I suppose I can legitimately release xgbgen under the WTFPL. To be fair, it is at least as complex as XGB itself. sigh

What follows is the original README:


XGB is the X protocol Go language Binding.

It is the Go equivalent of XCB, the X protocol C-language Binding (

Unless otherwise noted, the XGB source files are distributed under the BSD-style license found in the LICENSE file.

Contributions should follow the same procedure as for the Go project:


Last updated on 30 Nov 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

SocketSocket SOC 2 Logo


  • Package Issues
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc