Skip to content
Package84 repository health

go-winio

Windows-native IO utilities for Go, wrapping named pipes, overlapped I/O, and Win32 file handles behind idiomatic net.Conn and io interfaces.

Library Govv0.6.41,091 stars MIT License
go get github.com/Microsoft/go-winio
View source

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Excellent
  • Development activity88
  • Maintenance80
  • Community80
  • Maturity60
  • Momentum28

Technical analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation.How we score it →
Good
  • Architecture78
  • Code quality78
  • Innovation74
  • Learning curve55

go-winio is Microsoft’s library of low-level Windows IO primitives for Go programs, built directly on raw Win32 and NT syscalls rather than any cross-platform abstraction. Its core contribution is turning Windows named pipes into a standard net.Conn-compatible transport by driving overlapped IO through a shared IO completion port, so pipe reads and writes integrate with Go’s goroutine scheduler instead of blocking OS threads.

Beyond named pipes, the repository bundles a set of narrowly-scoped Windows subsystem wrappers: NTFS backup-stream and extended-attribute handling, security descriptor manipulation, process privilege adjustment, reparse point parsing, Hyper-V sockets, VHD and WIM image utilities, and an ETW (Event Tracing for Windows) provider implementation with a logrus hook. Each concern lives in its own file or subpackage, letting consumers import only what they need.

This is foundational infrastructure for the Windows container and virtualization ecosystem — it underpins projects like containerd, Moby/Docker, and the Windows Host Compute Service stack, which explains its emphasis on correctness for low-level OS interop over surface-level ergonomics. The //sys syscall directives and generated zsyscall_windows.go bindings reflect a deliberate choice to stay close to the Win32 API surface rather than layer on abstractions.

What You Get

  • Named pipe client/server support exposed as a standard net.Conn/net.Listener, usable anywhere Go code expects a stream connection
  • Non-blocking overlapped IO for arbitrary Win32 file handles, driven by a shared IO completion port instead of blocking OS threads
  • NTFS backup API bindings (BackupRead/BackupWrite) and a backuptar package for streaming Windows file metadata (ACLs, alternate data streams, reparse points) into and out of tar archives
  • Security descriptor and process privilege helpers (pkg/security, privilege.go) for reading/adjusting Windows ACLs and token privileges
  • An ETW (Event Tracing for Windows) provider implementation (pkg/etw) with a ready-made logrus hook (pkg/etwlogrus) for structured event tracing
  • VHD and WIM disk/image format utilities (vhd, wim) for creating and inspecting Windows virtual disk and imaging files
  • Hyper-V socket (hvsock) support for host-to-guest communication in virtualization scenarios

Common Use Cases

  • Implementing a Windows container runtime or shim (containerd/Moby-style) that needs named-pipe IPC with the Host Compute Service
  • Building a Windows service or agent that must copy files while preserving NTFS ACLs, alternate data streams, and reparse points
  • Adding ETW-based structured tracing to a Go service running on Windows, alongside existing logrus logging
  • Managing Hyper-V guest communication channels or working with VHD/WIM image files as part of a virtualization or provisioning tool
  • Adjusting Windows process token privileges (e.g. SeBackupPrivilege) for tools that need elevated backup/restore access

Under The Hood

Architecture

The package is organized as a flat set of concern-per-file modules at the root (pipe.go, file.go, backup.go, ea.go, sd.go, hvsock.go, privilege.go, reparse.go) alongside self-contained subpackages under internal/ (computestorage, fs, interop, socket, stringbuffer) and pkg/ (etw, etwlogrus, guid, security, process, bindfilter, fs), plus standalone format packages for vhd/, wim/, and backuptar/. Everything is gated behind //go:build windows build tags, and the whole library is built directly on syscalls rather than cross-platform abstractions. The central architectural pattern is the shared IO completion port initialized once (initIO/ioCompletionPort) and serviced by a background goroutine (ioCompletionProcessor), which every overlapped-IO-based type (named pipes, generic Win32 file handles) registers against — this is what lets blocking Win32 async APIs present as ordinary non-blocking Go io.Reader/io.Writer/net.Conn implementations without spinning up a thread per handle.

Tech Stack

The module targets Go 1.23 and has a deliberately thin dependency footprint: golang.org/x/sys for raw Windows syscalls, golang.org/x/tools supporting code generation, and github.com/sirupsen/logrus consumed only by the optional pkg/etwlogrus hook. Low-level Win32/NT function bindings are not hand-written — they’re declared via //sys comment directives and generated into zsyscall_windows.go by the bundled tools/mkwinsyscall code generator, invoked through go:generate. Continuous integration runs via GitHub Actions (ci.yml), with golangci-lint enforcing style and a DCO bot enforcing signed-off commits on every pull request.

Code Quality

The repository carries roughly twenty _test.go files spanning nearly every subsystem — pipes, extended attributes, security descriptors, Hyper-V sockets, GUIDs, ETW providers, VHDs, and tar streaming — built on Go’s standard testing package. Error handling favors explicit, typed Windows error values (e.g. ErrFileClosed, ErrTimeout implementing net.Error) over generic errors, and the generated syscall layer keeps unsafe pointer arithmetic isolated from the public API surface. Being Windows-only, most of this code cannot be exercised in a typical Linux CI runner without a Windows build agent, so test coverage depth is harder to verify from the repository alone than for cross-platform libraries.

What Makes It Unique

go-winio’s distinguishing choice is going straight to the NT/Win32 syscall layer instead of wrapping a higher-level Windows API, which is what lets it implement things the Go standard library structurally cannot: named pipes as first-class net.Conn, NTFS backup-stream semantics that preserve ACLs and alternate data streams, and ETW tracing. Its adoption as core plumbing inside containerd and Moby’s Windows container support is a strong signal that the abstractions it chose (completion-port-backed overlapped IO, backup-stream tar mapping) hold up under production use in container runtimes rather than just toy examples.

Used by 7 apps in this directory

Every app whose dependencies include github.com/Microsoft/go-winio, nine to a page.

TypeScript 50%Apache 2.0

agent-orchestrator

14,975

AI Agents · AI Code Assistants · Developer Tools

A local desktop workspace that gives every coding task its own agent, Git branch, and worktree, then tracks tasks, pull requests, CI, and reviews for 27 coding agents on one live Kanban board.

App
Built with
  • TypeScript 50%
  • Go 48%
Updated todayView details
Go 74%AGPL 3.0

Coder

17,450

Code Editors · Developer Tools · Devops

Self-hosted cloud development environments and AI coding agents — defined in Terraform, connected via WireGuard, automatically shut down when idle.

App
Built with
  • Go 74%
  • TypeScript 24%
Updated todayView details
Go 99%Other

Crush

29,153

AI Assistants · AI Code Assistants · Developer Tools

Your terminal coding companion — wire up any LLM with LSP intelligence, MCP extensibility, and a skills system that learns your workflow.

App
Built with
  • Go 99%
Updated todayView details
Go 97%Apache 2.0

Docker (Moby)

72,304

Developer Tools · Devops

The open-source container engine at the heart of Docker — a modular toolkit of runtime, build, and networking components for assembling container-based systems.

App
Built with
  • Go 97%
Updated yesterdayView details
Go 95%MIT

cli

18,173

Developer Tools · Team Chat

The official Lark/Feishu CLI tool built for both humans and AI agents, delivering 200+ commands and 26 AI agent skills across 18 business domains from messaging and calendar to docs, sheets, and approvals.

App
Built with
  • Go 95%
Updated 2 days agoView details
TypeScript 49%ZLIB

Portainer

38,875

Devops

A lightweight, open-source web UI that puts Docker, Kubernetes, and Podman management within reach of any team—no CLI expertise required.

App
Built with
  • TypeScript 49%
  • Go 39%
Updated yesterdayView details
Go 75%AGPL 3.0

Teleport

21,124

Authentication · Security

Zero-trust infrastructure access platform that replaces credentials and VPNs with short-lived certificates, SSO, and identity-aware proxies for SSH, Kubernetes, databases, RDP, and AI agents.

App
Built with
  • Go 75%
  • TypeScript 16%
Updated 4 days agoView details

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers