Skip to content
VIPS HandbookVIPS Handbook

Installation, linking, and ABI mismatches

Copy page

When an error appears during compilation, linking, or process startup, do not begin with the image-processing logic. First establish which libvips the compiler found and which dynamic library the program actually loads at runtime.

Symptoms

Section titled “Symptoms”
  • Wrong JPEG library version: the libjpeg linked at compile time conflicts with the version loaded at runtime.
  • Linking against the wrong libvips (when multiple versions are installed).
  • Operations that need a newer libvips (such as gifsave / heifsave) are not found on an older build.
  • M1/cross-compilation builds are missing platform symbols or ABI definitions at link time.

Approach

Section titled “Approach”

1. Confirm which library is linked

Section titled “1. Confirm which library is linked”

First confirm the govips version in use (for example go list -m -f '{{.Version}}' github.com/davidbyttow/govips/v2), then use ldd to confirm the actual path and version of the linked libvips and libjpeg.

终端窗口
# Example: show the dynamic libraries actually linked into the binary
ldd ./your-binary | grep -iE 'vips|jpe?g'

State version-sensitive conclusions as a specific libvips / govips version with a review date, and do not generalise “it runs on this version” to every version.

2. Distinguish the two error classes

Section titled “2. Distinguish the two error classes”
  • Missing symbol at compile time: #cgo or the link step cannot find a symbol — usually an include/library path in cgo or a cross-compilation toolchain issue.
  • Runtime library mismatch: it compiles, but startup or runtime reports a version error (such as a libjpeg conflict) — usually from LD_LIBRARY_PATH, the dynamic-linker cache, or several mutually conflicting versions on the system.

These have different debugging paths; decide which class you are in first.

3. Version-gated operations

Section titled “3. Version-gated operations”

Operations such as gifsave and heifsave require a newer libvips; not found or image too large often means the runtime libvips is older than the one used at compile time. Aligning the compile-time and runtime libvips versions removes this “compiles but will not run” class of oddity.

4. Cross-compilation notes

Section titled “4. Cross-compilation notes”

M1 / cross-compilation environments commonly fail to link because the target platform’s platform symbols or ABI definitions are missing. Install the target-platform dependency libraries and point #cgo at the correct cross-link flags.

Affected versions and scope

Section titled “Affected versions and scope”
  • Compile-time and runtime are aligned and link the correct library — the error is usually something else.
  • The ABI matches but a functional parameter (such as an operation boundary) differs — different-version behaviour, not an install fault.
  • The current review baseline is govips v2.19.0 with libvips 8.17.3. macOS, Linux, and container images require platform-appropriate dynamic-library inspection tools.

Sources

Section titled “Sources”

Version and ABI behaviour depends heavily on the build environment. Base conclusions on the libvips and dependency libraries actually loaded by the target system.