Apr 28, 2025
Input and output are fundamental to almost every program. Reading a file, sending an HTTP response, processing a byte stream, or copying data between connections all involve moving data from one place to another.
Go approaches this problem with a small set of interfaces in the io package. Rather than requiring every data source or destination to have a specific concrete type, Go defines simple contracts that many different types can implement.
Understanding these contracts is the key to understanding I/O in Go.
At the center of Go’s I/O model are io.Reader and io.Writer.
A Reader provides a way to read data into a byte slice.
type Reader interface {
Read(p []byte) (n int, err error)
}
The Read method attempts to read data into p. It returns the number of bytes read and an error, if any.
For example:
buf := make([]byte, 1024)
n, err := r.Read(buf)
if err != nil && err != io.EOF {
return err
}
process(buf[:n])
The important detail is that n tells you how many bytes are valid. The entire buffer should not be treated as meaningful data.
A Reader does not have to fill the buffer. It may return fewer bytes than requested, even when it has not reached the end of the input.
A Writer provides a way to write bytes to a destination.
type Writer interface {
Write(p []byte) (n int, err error)
}
The returned n indicates how many bytes were written. If fewer bytes are written than requested, Write must return a non-nil error.
For example:
n, err := w.Write([]byte("Hello, Go!"))
if err != nil {
return err
}
if n != len("Hello, Go!") {
return io.ErrShortWrite
}
In practice, standard library implementations commonly handle short writes by returning an error. The interface still makes the byte count explicit, allowing callers to handle the result correctly.
Consider a function that reads a file directly:
func ProcessFile(f *os.File) error {
// Process the file.
return nil
}
This function is coupled to *os.File. It cannot directly accept an HTTP response body, a byte buffer, or another custom data source.
Now consider a function that accepts io.Reader:
func Process(r io.Reader) error {
// Process the input stream.
return nil
}
The function can now work with any value that implements io.Reader.
Process(file)
Process(resp.Body)
Process(bytes.NewReader(data))
The function no longer needs to know where the data comes from.
This is one of Go’s most useful design patterns: depend on the behavior you need, rather than the concrete implementation that happens to provide it.
When a reader has no more data to provide, it may return io.EOF.
A common mistake is to treat every non-nil error as a failure. In Go, EOF is often the normal signal that a stream has ended.
The conventional reading loop looks like this:
func ReadAll(r io.Reader) ([]byte, error) {
var result []byte
buf := make([]byte, 4096)
for {
n, err := r.Read(buf)
result = append(result, buf[:n]...)
if err == io.EOF {
return result, nil
}
if err != nil {
return nil, err
}
}
}
Notice that the bytes are processed before the error is checked. A reader is allowed to return both data and an error in the same call.
For production code, the standard library already provides io.ReadAll, which handles this logic for you:
data, err := io.ReadAll(r)
if err != nil {
return err
}
Use io.ReadAll when the entire input is reasonably small and can fit in memory. For large or unbounded streams, process data incrementally instead.
The real power of Go’s I/O interfaces comes from composition.
Because readers and writers share common contracts, operations can be combined without introducing a new abstraction for every possible combination.
The io.Copy function transfers data from a reader to a writer:
n, err := io.Copy(dst, src)
if err != nil {
return err
}
fmt.Printf("Copied %d bytes\n", n)
The source might be a file, a network connection, or an in-memory buffer. The destination might be another file, a response writer, or a connection.
The copying logic remains the same.
The io package also provides adapters that turn existing values into readers or writers.
For example, io.LimitReader restricts how many bytes can be read:
limited := io.LimitReader(r, 1024)
data, err := io.ReadAll(limited)
if err != nil {
return err
}
Even if the original reader contains much more data, the adapter exposes at most 1024 bytes.
This style of composition makes it possible to build useful pipelines from small, focused components.
The io package contains several additional interfaces for more specialized behavior.
io.Closer represents a resource that can be closed.io.Seeker supports changing the current position in a stream.io.ReaderAt reads from a specific offset without relying on a shared current position.io.WriterTo allows a value to write its contents directly to a destination.io.ReaderFrom allows a destination to read data directly from a source.These interfaces are intentionally small. A type only needs to implement the capabilities it actually supports.
For example, not every reader can seek. A network connection is generally a stream, not a randomly accessible file. Requiring every reader to implement Seek would make the abstraction unnecessarily restrictive.
The design of io demonstrates an important principle: a small interface can support a surprisingly large ecosystem of implementations.
A function that accepts io.Reader can work with files, network connections, decompression streams, encrypted streams, test doubles, and custom implementations.
Each component can focus on one responsibility while relying on a shared contract.
This also makes testing easier. A test can provide an in-memory reader instead of creating a temporary file or starting a network server.
input := strings.NewReader("hello")
data, err := io.ReadAll(input)
if err != nil {
return err
}
fmt.Println(string(data))
The same function that processes real input can be tested with deterministic in-memory data.
Go’s I/O model is built around a simple idea: data sources and destinations should communicate through small behavioral interfaces.
io.Reader and io.Writer make this possible. The rest of the package builds on those foundations, providing copying, limiting, composition, and resource-management primitives.
Once these interfaces become familiar, many parts of the Go standard library begin to feel consistent. Files, HTTP bodies, buffers, compression streams, and network connections become different implementations of a common model.
That is the real elegance of Go I/O: not a complicated framework, but a small vocabulary for building systems from interchangeable parts.
Related tags: