Symbol doesn't match copy in library

What this error means

Every placed symbol carries a snapshot of its library definition inside the schematic file (the lib_symbols section) — that cache is why a schematic opens on a machine without your libraries. This check compares the snapshot against what the library contains now: ERC resolves the symbol's library nickname through the symbol library tables, loads the current version, flattens any inheritance from parent symbols, and compares the result against the cached copy. Any difference in the symbol definition counts: pins matched by pin number and their placement, graphic shapes, unit count, which fields exist, footprint filters, keywords.

Two boundaries matter. The comparison is between two library definitions, so edits to the placed instance (setting a resistor's Value to 10k, filling in the Footprint field) never trigger it. And if the library or symbol can't be found at all, that's lib_symbol_issues; this warning means the symbol was found and is different.

Symbols containing duplicated pin numbers are skipped by the comparison entirely.

Common causes

1. The library changed after the symbol was placed

The cache is a snapshot from the moment of placement. Any later edit to the library diverges from it: your own tweak in the Symbol Editor, a teammate's commit to a shared library, or a KiCad upgrade — the official libraries revise symbols between major releases, which is why this warning hits many symbols at once after moving a project to a new KiCad version.

2. The nickname resolves to a different library on this machine

The schematic stores only the nickname (mylib:LM358); the symbol library tables decide which file that means. On a machine where the nickname points to a different or older file — a handoff without the original libraries, a stale fork — every symbol from that library can mismatch against a file the schematic was never drawn from.

How to fix it

Update the cached copy from the library

Tools → Update Symbols from Library… (same path in KiCad 9 and 10; or right-click one symbol → Update Symbol…).
Choose the scope: all symbols, the selection, or symbols matching a reference, value, or library identifier.
Click Update, then re-run ERC (Inspect → Electrical Rules Checker).

Use when: The library has the version you want and the schematic is carrying an old snapshot — including the post-upgrade flood of warnings.

Look at the difference before deciding

Inspect → Compare Symbol With Library (or right-click the violation in the ERC window).
The Summary tab lists each difference; the Visual tab overlays the two versions.

Use when: You don't know which side is right. A changed pin type deserves a look before either version overwrites the other.

Point the nickname at the correct library

Preferences → Manage Symbol Libraries…, Project Specific Libraries tab.
Fix where the flagged symbol's nickname points (or add the project's own library ahead of a same-named global one).
Re-run ERC.

Use when: The mismatch appeared after moving the project to another machine or reorganizing libraries. Updating symbols from the wrong library would silently rewrite them; fix the table first.

When it’s safe to exclude

More defensible than for most ERC checks, but only in a design you are no longer editing. The warning has no electrical meaning of its own — the cached copy is what the netlist and PCB use, and it keeps working however far the library drifts.

In an active design, keep it: it is the only thing telling you that the next Update Symbols from Library will change the schematic, and by how much. For a frozen project where drift is expected, downgrading the severity in Schematic Setup → Electrical Rules → Violation Severity is more honest than excluding markers one by one (each newly drifted symbol would mint a new marker to exclude).

Gotchas

The comparison is strict: a pin nudged one grid square in the library counts. The checked-in repro is exactly that, and nothing else.
What counts differs by version. KiCad 9 ignores the library symbol's Value text (verified: changing only the Value produces no warning under 9.0.3); KiCad 10 compares field text directly, so the same edit counts there.
Symbols with duplicated pin numbers are exempt in KiCad 9 and 10 — a fix for KiCad 8's false positives on such symbols. The flip side: a genuine library change to one of those symbols never raises this warning.

Version notes

KiCad 9.0: Check introduced in this release.

Minimal reproduction

Two-minute version: place a symbol from a library you can edit, open it in the Symbol Editor, move one pin by one grid square, save the library, and re-run ERC (Inspect → Electrical Rules Checker). The placed symbol reports:

[lib_symbol_mismatch]: Symbol 'U_MM' doesn't match copy in library 'repro_mismatch'
    ; warning

The checked-in repro in data/erc/samples/lib_symbol_mismatch/ is this scenario in file form. Because the check needs a real library to compare against, the sample is a directory: the schematic (cached symbol, pin at one position), a one-symbol library with the pin moved, a sym-lib-table mapping the nickname, and a minimal .kicad_pro — without a project file, kicad-cli never loads the project library table and reports lib_symbol_issues instead. The run yields exactly one violation, and editing the cached pin to match the library (the update fix in file form) drops it to zero.

FAQ

ERC says the symbol has been modified in the library, but I haven't changed anything. Why?

Something did change, just not necessarily by your hand: a KiCad upgrade that revised the official libraries, a library file updated by a teammate, or the nickname resolving to a different file than on the machine where the symbol was placed. Run Inspect → Compare Symbol With Library on the flagged symbol; the Summary tab names each difference, which usually identifies the culprit immediately.

After upgrading KiCad, dozens of symbols don't match the library. Do I have to update them all?

No. The bundled libraries changed between releases while your schematic still carries the old snapshots, which keep working as-is. To bring them current, run Tools → Update Symbols from Library with "Update all symbols in schematic". If the design is frozen, leave the cache alone and downgrade this check's severity instead.

My schematic symbols no longer match the library after moving the project to another computer. What happened?

The schematic names libraries by nickname, and each machine's symbol library tables decide what a nickname points to. On the new machine it resolves to a different or older file, so the cached copies no longer match. Fix the entry in Preferences → Manage Symbol Libraries so it points at the library the project was drawn from — don't update symbols from the wrong library.

Sources

Reviewed against KiCad 9.0.3 on October 31, 2026. Every claim on this page was checked with kicad-cli sch erc.