The plugin Package — Specification¶

Focus: Authoritative reference for Go's built-in plugin package — the API, the -buildmode=plugin toolchain mode, the shared object file format, symbol export rules, type identity contract, and compatibility requirements.

Sources: - plugin package documentation: https://pkg.go.dev/plugin - cmd/go build modes: https://pkg.go.dev/cmd/go#hdr-Build_modes - Go source: https://github.com/golang/go/tree/master/src/plugin

Scope. This chapter is the deep-dive on only the plugin package. The broader survey of plugin mechanisms (RPC, WASM, c-shared, subprocess) lives in 08-plugins-dynamic-loading.

1. What the plugin package is¶

The plugin package loads a separately compiled Go shared object (.so) into a running Go program and exposes its top-level exported identifiers as runtime symbols. It is the only first-party in-process plugin mechanism in the standard library.

2. The API surface¶

The package exposes exactly two named types and two functions.

package plugin

type Plugin struct { /* unexported */ }
type Symbol  interface{}

func Open(path string) (*Plugin, error)
func (*Plugin) Lookup(symName string) (Symbol, error)

There is no Close, no Unload, no iterator over symbols, no introspection. The package is intentionally small.

3. Building a plugin¶

go build -buildmode=plugin -o myplugin.so ./pkg/myplugin

Constraints enforced by the toolchain:

The build produces a position-independent shared object that the system dynamic loader (dlopen on Unix) can map into the host process.

4. Loading a plugin¶

package main

import (
    "fmt"
    "plugin"
)

func main() {
    p, err := plugin.Open("./myplugin.so")
    if err != nil {
        panic(err)
    }
    sym, err := p.Lookup("Greet")
    if err != nil {
        panic(err)
    }
    greet := sym.(func(string) string)
    fmt.Println(greet("world"))
}

plugin.Open does three things, in order:

1. Calls dlopen on the file.
2. Runs every init function in the plugin and its transitive imports that the host has not already initialized.
3. Returns the *Plugin once init completes.

If any step fails, the plugin is unmapped and an error is returned.

5. Lookup semantics¶

sym, err := p.Lookup("Counter")
counter := sym.(*int64)        // variable lookup yields a typed pointer
atomic.AddInt64(counter, 1)

You must know the exact type at the call site to type-assert. Lookup never coerces; a mismatched assertion panics.

6. Symbol naming and visibility¶

The full set of lookable symbols is determined at link time; nothing can be added after the plugin is built.

7. Type identity contract¶

For a value crossing the plugin boundary to be type-asserted in the host, the type must be identical in both binaries.

Identity requires all of:

If any differ, reflect.Type equality returns false and type assertions panic. The error you see is usually a panic at the assertion site, not at Open.

8. Init semantics¶

The plugin's init functions run synchronously inside plugin.Open. This has practical consequences:

9. No unload¶

There is no API to unload a plugin. Once loaded:

• The plugin's code pages stay mapped for the lifetime of the host process.
• The plugin's global variables stay live.
• The runtime continues to know about its types and goroutines.

The Go authors have declined to add unloading because the runtime keeps unsafe references (type descriptors, finalizer pointers, goroutine stacks) into the plugin's address range. Safe unloading would require auditing every escape route.

10. Platform support¶

The absence of Windows support has been an open issue since 2016 and is the single biggest reason teams avoid the plugin package in cross-platform products.

11. Compatibility requirements¶

For plugin.Open to succeed and stay stable, host and plugin must share:

• The exact Go toolchain version (go.mod go directive + GOTOOLCHAIN).
• GOOS, GOARCH, GOAMD64 (and other microarchitecture variants).
• Build tags (-tags).
• -trimpath setting (mismatched paths change object hashes).
• The on-disk byte content of every package imported by both sides.

In practice this means building host and plugin from the same module checkout with the same go command. Any other setup invites cryptic load failures and version-mismatch errors.

12. Error conditions¶

plugin.Open and Lookup return errors as strings. Common cases:

Programmatic detection of these cases requires string matching; there are no typed errors.

13. Shared API package pattern¶

The recommended structure for a plugin ecosystem:

ecosystem/
├── go.mod
├── pluginapi/        # interfaces and request/response types
│   └── api.go
├── host/             # the binary that loads plugins
│   └── main.go
└── plugins/
    ├── alpha/        # built as alpha.so
    │   └── alpha.go
    └── beta/         # built as beta.so
        └── beta.go

Both host and plugins import ecosystem/pluginapi. The host calls a known factory symbol (e.g. New() pluginapi.Plugin) and uses the returned interface. Types crossing the boundary are interface-typed, never concrete.

14. When to use this package (narrow)¶

Use the plugin package only when all of the following hold:

• You target Linux (or macOS), exclusively.
• Host and plugins are built from the same monorepo, in lockstep, by the same CI.
• You need in-process call latency (sub-microsecond) and the alternatives' overhead is unacceptable.
• You accept that a plugin crash kills the host.

In all other cases prefer RPC plugins, WASM, or subprocess — see 08-plugins-dynamic-loading for the comparative survey.

15. Related references¶

• plugin package: https://pkg.go.dev/plugin
• -buildmode=plugin documentation: https://pkg.go.dev/cmd/go#hdr-Build_modes
• Broader plugin survey: 08-plugins-dynamic-loading
• Caddy's plugin architecture: https://caddyserver.com/docs/extending-caddy
• Go issue tracker for plugin on Windows: https://github.com/golang/go/issues/19282