# When to Use the `/examples` Directory in Go Projects: A Complete Guide

> Learn when to use the /examples directory in Go projects for runnable demonstrations, educational content, and integration tests. Understand this project layout convention.

- Repository: [golang-standards/project-layout](https://github.com/golang-standards/project-layout)
- Tags: best-practices
- Published: 2026-03-06

---

**The `/examples` directory is a conventional location for runnable, self-contained programs that demonstrate how to use your Go library or application, typically reserved for public libraries, complex applications, educational material, and integration testing.**

The `golang-standards/project-layout` repository defines the de facto standard for organizing production-grade Go codebases. Understanding when to use the `/examples` directory in Go projects helps maintain clean repository boundaries while providing essential, executable documentation for consumers of your code.

## What Is the `/examples` Directory?

According to the project layout standard, this directory holds runnable snippets illustrating how to use the code—whether it is an application, library, or utilities. The repository's root [`README.md`](https://github.com/golang-standards/project-layout/blob/main/README.md) lists `/examples` among the top-level directories and links to its dedicated README for implementation details【/cache/repos/github.com/golang-standards/project-layout/master/README.md†L165-L169】.

The [`examples/README.md`](https://github.com/golang-standards/project-layout/blob/main/examples/README.md) clarifies that this folder contains "Examples for your applications and/or public libraries" and provides external references for guidance【/cache/repos/github.com/golang-standards/project-layout/master/examples/README.md†L1-L9】.

## When to Add an `/examples` Directory

Include this directory when your repository contains reusable code that benefits from live demonstrations. The following situations warrant adding examples:

### Public Libraries

**Demonstrate your library's API** and show idiomatic usage to reduce the learning curve for downstream developers. Place small programs with a `main` package that import the library and exercise core features.

### Complex Applications

**Highlight entry points, configuration patterns, or integration points** such as CLI flags and HTTP servers. Include end-to-end example binaries that build and run with a single `go run ./examples/...` command.

### Teaching and Documentation

**Provide hands-on code** that developers can copy into the Go Playground or local workspaces. These short, self-contained examples reinforce written documentation without requiring extra setup.

### Testing Edge Cases

**Serve as integration-style examples** that verify the public contract across versions. These are example programs compiled in CI pipelines using commands like `go test -run Example`.

### Showcasing Best Practices

**Give concrete references for recommended patterns** including error handling, context usage, and architecture. Use representative scaffolding that mirrors the repository's recommended structure using `/cmd`, `/internal`, and `/pkg`.

## When to Skip the `/examples` Directory

Do not create this directory if your project is a tiny script or single-file utility, as it adds unnecessary noise. Also avoid it when comprehensive unit tests and documentation already cover all usage scenarios, preventing duplicate effort.

## Structuring Go Examples

Effective examples are self-contained and reference the repository's internal structure. They should compile with a single `go run` command.

### Library Usage Example

Create [`examples/hello/main.go`](https://github.com/golang-standards/project-layout/blob/main/examples/hello/main.go) to demonstrate public API consumption:

```go
package main

import (
	"fmt"
	"github.com/golang-standards/project-layout/pkg/hello"
)

func main() {
	// Demonstrates the public API of the `hello` package.
	msg := hello.Greet("World")
	fmt.Println(msg) // Output: Hello, World!
}

```

Run with: `go run ./examples/hello`.

### Application Bootstrap Example

For complex applications, create [`examples/server/serve.go`](https://github.com/golang-standards/project-layout/blob/main/examples/server/serve.go) showing integration:

```go
package main

import (
	"log"
	"net/http"

	"github.com/golang-standards/project-layout/internal/app/server"
)

func main() {
	srv := server.New()
	log.Println("Listening on :8080")
	if err := http.ListenAndServe(":8080", srv); err != nil {
		log.Fatalf("server failed: %v", err)
	}
}

```

Run with: `go run ./examples/server`.

## Key Files in the Standard Layout

Understanding the reference documentation helps implement this convention correctly:

- **[`README.md`](https://github.com/golang-standards/project-layout/blob/main/README.md)**: The root file mentions `/examples` in the overview and links to its dedicated documentation【/cache/repos/github.com/golang-standards/project-layout/master/README.md†L165-L169】.
- **[`examples/README.md`](https://github.com/golang-standards/project-layout/blob/main/examples/README.md)**: Defines the directory's purpose and lists external reference projects【/cache/repos/github.com/golang-standards/project-layout/master/examples/README.md†L1-L9】.
- **Example program files**: Concrete implementations like [`examples/hello/main.go`](https://github.com/golang-standards/project-layout/blob/main/examples/hello/main.go) or [`examples/server/serve.go`](https://github.com/golang-standards/project-layout/blob/main/examples/server/serve.go) illustrate component usage.

## Summary

- The `/examples` directory stores runnable demonstrations for libraries and applications.
- Add it for public APIs, complex architectures, educational content, and CI integration tests.
- Keep examples self-contained and executable with `go run ./examples/...`.
- Omit it for single-file utilities or when tests already provide sufficient documentation.
- Structure examples to mirror the repository's layout using `/internal`, `/pkg`, and `/cmd`.

## Frequently Asked Questions

### Should I put example tests or unit tests in the `/examples` directory?

Unit tests belong in `*_test.go` files within their respective packages. The `/examples` directory is specifically for standalone `main` packages that demonstrate real-world usage. However, you can compile examples in CI to serve as integration tests using `go test -run Example`.

### Can I have multiple example applications in subdirectories?

Yes, organize related examples into subdirectories like `examples/cli/` and `examples/web/`. Each subdirectory should contain its own `main` package and be runnable independently with `go run ./examples/cli` or `go run ./examples/web`.

### How do I import my own package in `/examples` code?

Use the full module path as declared in your `go.mod` file. For instance, if your module is `github.com/org/project`, import internal packages like `github.com/org/project/internal/app/server` or public packages like `github.com/org/project/pkg/hello` in your example files.

### Is the `/examples` directory required for every Go project?

No, the directory is optional. Single-file utilities or internal tools without external consumers do not need examples. Only add it when downstream developers or new team members would benefit from seeing executable usage patterns.