Step 1: Launch from a terminal and read the actual error

As general Linux guidance, a program started from a terminal prints its failure to that terminal instead of swallowing it. Open a terminal and run the program by name — gerbv if it is installed system-wide, or the full path to the executable if you are testing a local build. If a shared library is missing, the loader says so, in a message whose substance is that a named library file could not be opened or found, and it names the library. Write that name down exactly; it is the diagnosis and most of the prescription in one line. If instead the program starts happily from the terminal, the software was never broken — the launcher entry is, and recreating the shortcut or menu entry is the fix. Either way, thirty seconds in a terminal replaces an afternoon of reinstalling things at random, and this step comes first for every won’t-start problem, not just this one.

Step 2: Understand what is missing — the GTK 2 runtime

Gerbv’s user interface is built on GTK 2 — that is the project’s current, documented state; a port to a newer GTK is a stated plan, not a shipped change. A consequence follows for modern distributions: a fresh Linux installation may carry newer toolkit versions for other software while having no GTK 2 runtime at all, because nothing else on the machine needs one. In that situation Gerbv’s code is fine and its libraries are simply absent, and the loader’s complaint will name a GTK or related library — the runtime set around GTK 2 includes companions such as GLib, Cairo and Pango, any of which can be the specific file named first. Installing the missing runtime libraries through your distribution’s package manager, as general guidance, resolves the whole family at once, because the package manager installs the chosen library’s own dependencies alongside it. Do not download individual library files from the web and copy them into system folders — that path leads to version mixtures that no package manager can later untangle.

Step 3: Prefer the official packages — dependencies handled for you

The cleanest way to never meet this problem is to install Gerbv the packaged way. The 2.13.0 release ships an official .deb built for Debian 13 and Ubuntu 22.04, and an official .rpm built for Fedora 43, alongside the other platform builds. Installing a .deb with your system’s package tooling, or an .rpm with its equivalent, lets the package manager read the package’s declared dependencies and install the GTK 2 runtime pieces automatically — that dependency resolution is the entire reason distribution packages exist. Match the package to the distribution family: .deb for Debian and Ubuntu systems, .rpm for Fedora systems, and do not force a package built for one family onto another. If your distribution offers Gerbv through its own repositories, that build is also dependency-complete by construction, though it may lag the current release — the install guide discusses the trade-off. Building from source is the route where library-hunting is genuinely your job: the project’s documented build requirements are headed by the GTK 2 development package alongside GLib, CMake and Ninja, and a machine set up to build Gerbv has, by that fact, the runtime it needs.

Other causes worth ruling out

If the terminal shows no library complaint, work through the remaining causes. Wrong architecture or build: the official builds target 64-bit (amd64) systems; a binary that cannot execute belongs to a different platform and must be replaced with the correct package. A stale older install: an old distro-packaged Gerbv and a new manual install can shadow each other, so confirm which executable the gerbv command resolves to, and keep one route per machine. Permissions on a local build: an executable lacking execute permission fails plainly at the terminal — grant it via the file manager or the usual command, for files you built or verified yourself only.

Stepwise recap

1. Run gerbv in a terminal and capture the exact failure line.
2. If a library is named, install that runtime library via the distribution package manager — expect GTK 2 and its companions to be the family involved.
3. Reinstall the packaged way where possible: official .deb on Debian/Ubuntu, official .rpm on Fedora, letting dependencies resolve automatically.
4. Rule out the rest: correct 64-bit package for the platform, one clean installation route, execute permission on local builds.
5. Confirm with a real file: open a board set with how to open Gerber files as the final proof.

Prevention

Install packaged software with the package manager, keep one route per application, and when any Linux GUI program fails silently in future, reach for the terminal before the reinstall. The pattern generalises far beyond Gerbv: on Linux, the error message almost always exists — it is merely waiting for a terminal to be printed in.

Frequently asked questions

Why does Gerbv need GTK 2 libraries specifically?

Gerbv’s interface is built on GTK 2 — a newer GTK port is a stated plan, not a shipped change. A modern distribution may not include the GTK 2 runtime by default, so installing the official package, which pulls its dependencies automatically, is the reliable route.

How do I find out why Gerbv will not start?

Launch it from a terminal by typing gerbv and reading the output. A missing shared library is named in the message; install that runtime library through your distribution’s package manager rather than downloading library files manually.

Which package should I install on my distribution?

Use the official .deb on Debian and Ubuntu systems and the official .rpm on Fedora systems — the 2.13.0 packages were built for Debian 13, Ubuntu 22.04 and Fedora 43. Let the package manager resolve and install the dependencies.

Step 1: Extract the ZIP and see what you actually have

Download gerbv_v2.13.0_.macOS.zip (6,795,082 bytes) and extract it in your Downloads folder or wherever you keep applications-in-progress. Extraction itself can be the first small stumbling block: if a double-click on the ZIP appears to do nothing, look for the extracted folder beside the archive before downloading again, because macOS extracts quietly. Inside, you should find the Gerbv application bundle. Do not move it into Applications yet — keep this first launch controlled and local, confirm the app runs, and only then file it away properly. If what extracted is not an application bundle, or the archive name differs from the one above, stop and re-download through the download page rather than improvising with an unexpected file.

Step 2: Verify the SHA-256 before the first open

The published SHA-256 for the Gerbv 2.13.0 macOS ZIP is:

7d79adf7556508baa6c9d080949866371cbb49809f2082e0e6639cb62c4dba0f

macOS can check this with a built-in command. Open Terminal, change to the folder holding the ZIP, and run:

shasum -a 256 gerbv_v2.13.0_.macOS.zip

Compare the printed value with the one above. An exact match means the archive on your disk is the published release archive, and proceeding past Gatekeeper is a decision you are making about verified software. A mismatch means the opposite: delete the file, re-download through the download page, and check again — no right-click technique legitimises a file whose bytes are not the release. Verify the ZIP, not just the extracted app, because the ZIP is the artefact the project published and hashed.

Step 3: Open the unsigned app the per-app way

With a verified download, handle Gatekeeper as general macOS guidance describes for unsigned apps you have chosen to trust on evidence. Do not double-click for this first launch — a plain double-click is what Gatekeeper blocks. Instead, right-click (or Control-click) the app and choose Open from the context menu. macOS then shows a dialog naming the app and asking whether you are sure you want to open it; confirm Open. That single confirmed open records your decision for that app, and subsequent launches work normally by double-click. If you instead find a note in your security settings saying the app was blocked, with an option to open it anyway there, that is the same per-app decision reached by another door — use whichever macOS presents, provided the app named is the Gerbv you just verified, and provided you reach it immediately after your own blocked launch rather than finding a stale entry from some earlier, forgotten attempt.

What not to do

Do not disable Gatekeeper globally. As general macOS guidance, the system-wide off switch exists for managed environments, not as a consumer fix: it removes the check for every future download, including the malicious one that will eventually arrive dressed as something you wanted. The right-click method exists precisely so that one verified app can be excepted while the protection stands for everything else. Likewise, do not strip security attributes from the app with terminal commands copied from a forum, and do not re-download from a site promising a pre-unblocked or installer-wrapped copy — the ZIP on the download page, hash-verified, is the entire supply chain you need. Finally, if a first launch still fails after a verified hash and a confirmed Open, read any message macOS shows word for word before acting; platform issues beyond Gatekeeper are handled in the macOS install guide, and guessing at system settings helps none of them.

After the first open

Once Gerbv runs, move the app to Applications if you have not already, and open a first board set following how to open Gerber files so the session ends with the viewer doing its actual job. An alternative installation route also exists — Homebrew lists Gerbv 2.13.0 — and the install guide discusses when that route suits better than the ZIP. Either way, the Gatekeeper lesson transfers to other small open-source Mac software: verify first, except per-app, and leave the system protection switched on.

Prevention

For future releases, repeat the same two-minute shape: download the new ZIP from the download page, check its published hash for that version (hashes are per-file and per-release — never reuse this version’s value for the next), and right-click Open on first launch. The habit costs almost nothing and converts Gatekeeper from an annoyance into what it is designed to be — the moment you pause and prove what you are about to run.

Frequently asked questions

Why does Gatekeeper block Gerbv on macOS?

The 2.13.0 macOS build is distributed as an unsigned application outside the App Store, and Gatekeeper treats unrecognised, unsigned apps cautiously by default. Verify the ZIP’s SHA-256 first, then use the per-app Open method rather than changing system settings.

Is there a .dmg installer for Gerbv on macOS?

No. The official macOS artefact for 2.13.0 is a ZIP — the first official macOS build shipped in that release. A supposed Gerbv .dmg from another site is not the project’s release and should not be used.

Should I disable Gatekeeper to install Gerbv?

No. Disabling Gatekeeper removes the check for all future downloads. Right-click the verified app, choose Open, and confirm once — that excepts this one app while system protection stays on for everything else.

Why SmartScreen stops installers like this one

As general Windows guidance: SmartScreen checks programs you run from the internet against reputation information. Large commercial installers accumulate reputation quickly; small open-source projects, whose installers are new and downloaded by comparatively few people, often have little or no reputation at first — so Windows warns not because it found anything wrong with the file, but because it does not yet know the file. That distinction matters. The warning is a request to verify, not a verdict of danger, and equally not a formality to dismiss automatically. The safe behaviour is to supply the verification SmartScreen cannot: proof that the file on your disk is bit-for-bit the file the project published. For an open-source project with published hashes, that proof is available to anyone, for free, in a minute — which is exactly why the hash step below is not optional decoration.

Step 1: Confirm where the installer came from

Before any hash work, confirm the installer is the file you meant to download: gerbv-2.13.0-win64.exe, the Windows installer for Gerbv 2.13.0, obtained by following the download page’s link to the project’s release. If the file arrived from anywhere else — a random search result, a file-sharing mirror, an email attachment — stop here and re-download it through the download page instead of verifying a stranger. A hash check proves a file matches a published value; it cannot make an unwanted source trustworthy if you also copied the expected hash from that same source. Source first, hash second, in that order, always.

Step 2: Verify the SHA-256 hash — before running anything

The published SHA-256 for the Gerbv 2.13.0 Windows installer (15,062,430 bytes) is:

2bafa388c485a9bcecef40e8537cd90287e626f29ce20502ab472faf3cd349fb

Windows can compute the same value for your downloaded file without any extra software. Open PowerShell in the folder containing the installer and run:

Get-FileHash .\gerbv-2.13.0-win64.exe -Algorithm SHA256

Compare the output with the value above, character for character — or compare the beginning and end carefully if you paste both into a text editor. Three outcomes are possible. Exact match: the file is the published installer, untouched in transit; proceed to Step 3 with a clear conscience. No match: do not run the file, whatever SmartScreen or anyone says. Delete it and re-download through the download page; a mismatch means the bytes are not the release, whether through corruption or substitution, and Run anyway cannot fix that. You cannot get a result: the file is in a different folder from the PowerShell window, or the name differs — correct the path rather than skipping the check.

Step 3: Proceed past SmartScreen — only with a verified file

With a verified installer, the SmartScreen screen is handled as general Windows guidance describes for programs you have chosen to trust on evidence: on the SmartScreen prompt, choose More info, which expands the dialog and reveals a Run anyway option, then choose Run anyway and continue into the normal installation covered by the Windows install guide. Read the expanded dialog once before clicking — it names the app Windows could not recognise, and that name should be the installer you just verified. If the name is anything else, close the dialog and find out why a different program is trying to run. After installation, Gerbv should launch as a normal desktop application; Windows 10 is the tested platform for the current builds, they are 64-bit only, and Windows 7 support in Gerbv ended beyond release 2.8.0 — on a Windows 7 machine, no SmartScreen technique makes the current installer the right choice.

What not to do

Do not disable SmartScreen, or Defender, to make the warning go away — that trades a two-minute verification habit for a permanent hole, and it protects the next, genuinely unknown download even less than this one. Do not run an installer whose hash mismatches because the download site looked professional. And do not treat this guide as a blanket licence for Run anyway: the option is justified here by a specific sequence — known source, published hash, exact match — and any download that cannot complete that sequence has not earned the click. Prefer the ZIP build? Gerbv portable for Windows covers the MSYS2 ZIP variant, which extracts and runs without an installer at all — verify its hash the same way before first launch.

Prevention, for every future download

Make the sequence a reflex for small-project software generally: download from the project’s own release channel, verify the published hash before the first run, and let SmartScreen’s warning be the reminder that triggers the check rather than an obstacle to defeat. Two minutes, every time, is the entire cost of never having to guess whether an installer is genuine.

Frequently asked questions

Does a SmartScreen warning mean the Gerbv installer is malware?

No. As general Windows guidance, the warning means the program has little reputation information, which is common for small open-source installers. It is a prompt to verify — which the published SHA-256 hash lets you do conclusively before running anything.

The hash of my download does not match. What should I do?

Do not run the file. Delete it, re-download the installer through the download page so the source is the project’s release, and verify again. Run anyway is only justified after an exact hash match.

Should I turn SmartScreen off to avoid this in future?

No. Leave SmartScreen enabled. Verify each small-project download by its published hash, then use More info and Run anyway for that verified file only — the protection stays for everything else.

How to recognise RS-274D data

RS-274D, sometimes called Standard Gerber, dates from an era when the file held only movement and exposure commands. Two fingerprints give it away. The first is company: an RS-274D file travels with a separate aperture file — a wheel or aperture list, often with a name suggesting apertures, that defines what each aperture code (D-code) in the drawing actually means: its shape and size. The second fingerprint is absence: the RS-274D file itself contains no embedded parameter block declaring units, format and apertures, because that information lives outside it. RS-274X — Extended Gerber — folded all of that into the file itself, which is why an X file opens self-contained anywhere, and why a D file without its aperture companion is not a complete description of a board at all. If your archive contains an aperture list alongside sparse drawing files, or the files came from a very old CAD system or an archive of an old design, you are almost certainly holding RS-274D.

Why Gerbv cannot just read it anyway

This is not a missing-codec problem. An RS-274D command says, in effect, draw with aperture D12 — and D12 means whatever the external aperture file says. Without that file the geometry is undefined: the same command could be a fine line or a large pad. A viewer that guessed would produce a board-shaped fiction, worse than no picture at all. RS-274X removed the ambiguity by embedding apertures, units and format in the file. Treat a refusal here as a format verdict, not a malfunction. If the same set also fails the basic checks in Gerber files that will not open, resolve the format question first, because it sits underneath all the others.

Route 1: Re-export as RS-274X from the CAD tool (preferred)

If the design still exists in any reasonably current CAD tool, re-export solves everything at once. Open the design, choose the Gerber export, and select RS-274X — in most modern tools this is the default Gerber output and may simply be labelled Extended Gerber or X — then export the full layer set and the Excellon drill data in one pass, with one origin and one unit system, exactly as you would for a new board. The result is a modern, self-describing set that Gerbv opens directly, following how to open Gerber files. Re-export has a second advantage over conversion: the data comes from the design itself, not from an interpretation of an old drawing file, so nothing depends on reconstructing an aperture wheel correctly. Whenever the source design is reachable, this route is not merely preferable — it makes the conversion route unnecessary.

Route 2: Convert the RS-274D files

Sometimes the design is gone and only the old fabrication files survive — an archive, a former contractor’s delivery, a board that must be reproduced or studied as-is. Then conversion is the task: an RS-274D-to-RS-274X translation, in which the external aperture definitions are embedded into the file and the drawing commands are rewritten in the extended format. Two cautions govern this route. First, conversion is only as good as the aperture file: if the wheel file is missing or belongs to a different revision, the converted geometry will be wrong in ways that look plausible, so verify the converted set in Gerbv with unusual care — measure known features, compare against any surviving drawing or physical board, and treat the first view as a hypothesis. Second, use a conversion path you can inspect: Gerbv itself documents export to RS-274X among its export formats for data it can read, and CAD tools that still import RS-274D can typically re-export it as X, which is route 1 applied to the files rather than the design. What you should not do is send unconverted — or unverified converted — legacy data to a board house on the assumption that their toolchain will sort it out silently.

What about the drill files from the same era?

Old sets pair RS-274D artwork with drill data of a similar vintage. Excellon drill viewing is supported in Gerbv, and drill files from older workflows often load — but check them with the full discipline of viewing Excellon drill files: units, coordinate format and zero suppression were even less standardised in older exports, and an era-correct drill file can still be misread by modern assumptions. Overlay the drills on the converted copper and require centred holes everywhere before believing either file.

Prevention and archiving advice

If you maintain designs with any future, export a fresh RS-274X set now, while the CAD source is at hand, and archive it alongside the design files. Legacy formats do not become more supported with time. When you receive an old set from someone else, ask early whether it is D or X — that one question, asked before the troubleshooting starts, is the whole lesson of this page in miniature.

Frequently asked questions

How do I know my files are RS-274D and not RS-274X?

Look for a separate aperture or wheel file travelling with the drawing files, and for the absence of an embedded parameter block in the Gerber files themselves. RS-274X carries apertures, units and format inside the file; RS-274D keeps apertures outside it.

Can I make Gerbv open RS-274D with a setting or plugin?

No. Gerbv’s documented support is RS-274X only, and RS-274D is explicitly not supported, because the drawing commands are undefined without the external aperture file. Re-export or convert the data to RS-274X instead.

Is conversion as good as re-exporting from the design?

Re-export is better, because the data comes from the design itself. Conversion depends entirely on having the correct aperture file for that revision, so verify a converted set in Gerbv by measuring known features before trusting or sending it.

How a 25.4-times error looks in the viewer

Load a millimetre file under inch assumptions — or the reverse — and one of two scenes appears. In one, the board erupts past the window: a single corner, a few enormous traces and pads the size of dinner plates fill the view, because you are looking at a small region of a board drawn twenty-five times too big. In the other, the canvas looks empty at normal zoom, and only zooming far out or fitting the view reveals a miniature board, complete and correctly proportioned, sitting near the origin. Both scenes share the diagnostic gift of unit errors: relative measurements stay right while absolute ones are impossible. A footprint’s pads remain in the correct ratio to each other; the board outline remains the correct shape. The moment a measured dimension — check the outline against your known board size first — comes back at 25.4 times, or one twenty-fifth of, the intended value, you have the cause. Factors of ten alongside it suggest a coordinate-format problem as well, which the Excellon fixes guide treats for drill data.

Where units are declared in RS-274X

RS-274X files are self-describing in a way the older RS-274D format was not: the file itself carries parameter commands, set off by percent signs, near its head. The unit declaration is one of them — the MO (mode) parameter, written as %MOMM*% for millimetres or %MOIN*% for inches. Nearby, the format specification declares the coordinate digit layout used by the numbers that follow. You do not need to edit these by hand — you should not — but being able to open a Gerber file in a text editor and read its head tells you in seconds what the exporting tool actually declared, as opposed to what its dialog claimed. If the declaration says inches for a board you design in millimetres, the export preset is lying to you, and every downstream reader that trusts the file, Gerbv included, will draw the board at inch scale. Trust the file, then fix the preset.

Why the drill file often disagrees alone

A common partial version spares the Gerber layers and strikes only the drill data. Gerber and drill exports are separate operations in most CAD tools, often with separate unit settings on separate dialogs. Set millimetres on the Gerber page and forget the drill page, and the copper arrives correct while the holes arrive scaled or offset relative to it — positions right in shape, wrong in size or placement in exactly the patterns the drill guide describes. The lesson generalises: units are a per-output setting, not a project property, and a unit audit that only checks one output checks nothing. In Gerbv, the fastest audit is comparative: measure a known copper dimension, then a known drill dimension, and confirm both read true in the same session, overlaid as in load and align Gerber layers.

Stepwise fix

1. Measure the outline. Compare it with the intended board size. A ratio of about 25.4, in either direction, confirms a unit mismatch.
2. Read the file head. In a text editor, find the %MO..*% declaration in the Gerber file and note what it actually says.
3. Check every output. Inspect the Gerber layers and the Excellon drill file separately — find which outputs declare which units.
4. Fix the preset, not the file. In your CAD tool, set one unit system for all fabrication outputs, Gerber and drill, and save it in the preset.
5. Re-export and re-measure. Reload the fresh set in Gerbv and repeat the outline measurement before any other inspection.

Which unit should you export in?

Either — consistently. Board houses work in both systems, and RS-274X carries the declaration with the data, so a correctly declared inch file is not inferior to a millimetre file. The failures come from mixture and misdeclaration, never from the choice itself. Pick the system your design is native to, so the numbers you verify in the viewer are the numbers you think in, declare it on every output, and write it in the fabrication notes that travel with the set. If you inherit someone else’s files, read their declarations before assuming: a stranger’s inch board measured with millimetre expectations generates a support conversation that one look at %MOIN*% would have ended.

Prevention

Make units part of the pre-send ritual: one measured outline dimension, read against intent, on every set, every time. It takes seconds, it catches the entire family of unit and format scaling errors regardless of which output carries them, and it is the single highest-value measurement in this guide’s sibling, the measurement tutorial. A board that measures true at the outline can still have other problems — but it does not have this one.

Frequently asked questions

How can I tell a unit mismatch from other scaling problems?

Measure a dimension you know, such as the board outline. A ratio of about 25.4 to the intended value is the millimetre/inch signature. Relative proportions stay correct in a unit mismatch, which distinguishes it from a distorted or corrupt file.

Where do I check which unit a Gerber file uses?

Open the file in a text editor and read the parameter block at its head: the declaration appears as %MOMM*% for millimetres or %MOIN*% for inches. That declaration is what viewers, Gerbv included, honour.

Should I edit the unit declaration in the file by hand?

No. Fix the export preset in your CAD tool so every output — Gerber layers and the drill file — uses one declared unit system, then re-export the complete set and re-measure the outline in Gerbv.

What an Excellon file has to get right

An Excellon (NC drill) file is a list of tools, each with a diameter, and a list of coordinates where each tool drills. For Gerbv to draw it correctly over your copper layers, three declarations must match what the CAD tool intended: the units the numbers are written in, the coordinate format — how many digits sit before and after the implied decimal point — and the zero suppression mode, which says whether leading or trailing zeros may be omitted from coordinates. Get any one of the three wrong in the export, or mismatched between the program that wrote the file and the assumptions used to read it, and the same digits mean different holes. That is why drill bugs feel so strange: the file is not random, it is systematically misread, so the pattern looks almost right — just scaled, shifted, or with its sizes scrambled.

Size errors: diameters in the wrong unit

If every hole is uniformly too big or too small by the same proportion while positions are correct relative to the pads, suspect a unit mismatch applied to tool diameters. A tool defined as a fraction of an inch and read as millimetres, or the reverse, produces holes roughly twenty-five times — or a twenty-fifth — of the intended size, which at board scale reads as either giant craters covering their pads or pinpricks lost inside them. The subtler version affects only some tools: a library part whose holes were specified in a different unit from the rest contributes one implausible size to an otherwise sane tool list. Read the drill statistics Gerbv reports for the file — the list of tool sizes actually present — and compare it with the sizes your design intends. A size you do not recognise is a finding, not a curiosity: locate where that tool drills before the set goes anywhere.

Position errors, part 1: zero suppression

Excellon coordinates are commonly written without a decimal point, so the reader must reconstruct each number from its digits. Zero suppression is the convention that makes this work — and breaks it when writer and reader disagree. Under leading-zero suppression, trailing zeros are kept and leading zeros may be dropped; under trailing-zero suppression, the opposite. If a file written with one convention is interpreted with the other, coordinates collapse or stretch: holes pull toward one axis, cluster, or land at a fraction of their intended distance from the origin. The board-shaped pattern is still faintly recognisable, which is the clue — a truly corrupt file looks random, while a zero-suppression mismatch looks like the board passed through a distorting lens anchored at the origin. The fix is in the drill export: choose the suppression mode your workflow expects, state it consistently, and regenerate the drill file rather than trying to rescue the digits.

Position errors, part 2: format digits and origin

The coordinate format — for example, how many integer and decimal digits the numbers carry — must match between the Gerber export and the drill export, and between the drill file’s header and its contents. A digit mismatch produces the classic miniature board in the corner: every coordinate read ten or a hundred times too small, so the full hole pattern sits tiny near the origin. That presentation belongs to format, not to the board. Separately, a pattern that is the correct size and shape but shifted as a rigid block was exported against a different origin from the Gerber layers — the subject of Gerber layers misaligned, fixed by re-exporting Gerber and drill data in one pass against one origin. Distinguish the three: shrunk-to-corner means format digits, uniformly shifted means origin, distorted toward an axis means zero suppression. Each has its own one-line remedy at export, and none is remedied inside the viewer.

Stepwise fix

1. Classify the error. Sizes wrong but positions right, pattern shifted as a block, pattern shrunk to a corner, or pattern distorted — note which one you have.
2. Read the tool list. Compare the drill sizes Gerbv reports with your design intent, using measurement in Gerbv on a few representative holes against their pads.
3. Check the drill export settings. In your CAD tool, confirm the drill units match the Gerber units, the coordinate format digits match the header, and the zero suppression mode is the one your flow expects.
4. Re-export Gerber and drill together. One session, one origin, matching units and format — then reload both.
5. Re-run the overlay. Every hit centred in its pad, corner to corner, with sensible tool sizes, before the set is sent.

Prevention

Lock the drill settings into the same saved preset as the Gerber settings so the two can never drift apart, and treat the drill statistics read — sizes present, hit counts plausible — as a required step alongside the visual overlay. Most Excellon pain is a settings divorce between two exports that were once married; a single preset keeps them together.

Frequently asked questions

Why are all my drill holes the right position but the wrong size?

That signature points at tool diameters interpreted in the wrong unit. Read the tool sizes Gerbv reports, compare them with the design, and re-export the drill file with units that match the Gerber export.

My whole drill pattern is tiny in one corner. What happened?

The coordinate format — the number of integer and decimal digits — was read differently from how it was written, shrinking every coordinate by a power of ten. Fix the format digits in the drill export and regenerate the file.

What does zero suppression do in an Excellon file?

It is the convention for which zeros may be omitted from coordinates written without a decimal point — leading or trailing. If the file was written with one mode and read with the other, holes distort toward an axis. Set one mode in the export and use it consistently.

How misalignment presents

Read the pattern before reading the causes, because the pattern names the cause. A single layer shifted while all others agree points at that layer’s own export — a different origin, a mirrored output, or a stale file. All layers shifted together relative to the drill data, or drills shifted relative to all layers, points at two export runs that used different settings: typically the Gerber files exported in one session and the drill file in another. A shift that grows across the board — aligned in one corner, increasingly wrong toward the opposite corner — is not a shift at all but a scale disagreement, which means a format or unit difference between layers. A mirror image, where text reads backwards and asymmetric features swap sides, is a layer exported mirrored, usually a bottom layer produced with a mirror option intended for viewing rather than fabrication. Each pattern is fixed in a different place, so spend a minute classifying yours.

Cause 1: Layers exported with different origins

Every file must share one origin — one reference point for all coordinates. CAD tools let an export use the design origin, an absolute origin, or a user-placed origin, and if layers were plotted against different choices, they will be offset by the distance between those origins, everywhere, by the same amount. This happens most often when a set was not exported in one pass. The remedy is not to move anything in the viewer: re-export the entire set in one session, with one origin for every output, and reload.

Cause 2: Format and unit settings differ between layers

Gerber files declare their coordinate format and units inside the file, and the drill file declares its own. If layers were exported with different settings — one in millimetres, another in inches, or with different coordinate precision — the viewer honours each declaration and the stack disagrees, typically as a growing scale error rather than a clean shift. The full treatment of that signature is in millimetres vs inches, but the rule for this guide is the same: a scale-shaped misalignment is solved in the export settings, by giving every output — Gerber and Excellon alike — the same units and a compatible format, then re-exporting together. Check this cause especially when most layers came from one tool or preset and one file came from somewhere else, such as a drill file regenerated by a different utility.

Cause 3: Mixed revisions in one folder

The most human cause: the folder contains files from more than one export. A corrected top copper was copied in without removing the old one, so the stack shows a board arguing with its previous self. The tell is a small, design-like offset on one layer — a connector moved in the last edit — rather than a clean engineering offset. Clean the folder to one set from a single export, or extract the fabrication ZIP into a fresh folder and view that set instead.

Stepwise fix

1. Isolate the disagreement. Show layers in pairs — copper with mask, copper with silkscreen, copper with drills — and identify exactly which file disagrees with the consensus of the others.
2. Use the drill layer as reference. Load the Excellon file over the copper, as in viewing Excellon drill files. Holes must sit centred in pads across the whole board. Centred everywhere except one layer’s features confirms that layer as the outlier; holes offset from everything means the drill export used different settings.
3. Check for mirroring. Read silkscreen text and compare an asymmetric feature on both sides. Backwards text on a fabrication layer means a mirrored export.
4. Fix at the source. In your CAD tool, set one origin, one unit system and one format for all outputs, turn off any per-layer mirror that is not part of the fabrication intent, and re-export the complete set in one pass.
5. Reload and re-verify. Open the fresh set, restack it, and repeat the drill-overlay check corner to corner before trusting it.

What not to do in the viewer

Do not nudge a layer into apparent alignment and then order from the original files — the factory receives the files, not your view, so a hand-aligned stack proves nothing and can hide a broken export behind a reassuring picture. Gerbv does have documented export operations that translate data for format-conversion work, but an inspection session is not the place to repair registration. If the set does not align as exported, it is not ready. Our measurement guide, measure distances in Gerbv, turns the residual question — aligned, but by how much where it matters — into numbers you can check against the design.

Prevention

Prevent misalignment by making re-export boring: one preset, one origin, one unit system, all outputs in one pass, into a clean folder, every time. Never assemble a send-set by copying individual files between export generations. And make the drill overlay the last check before any upload, because the drill layer — unambiguous, mechanical, impossible to argue with — will witness a registration problem that layer-to-layer eyeballing can miss.

Frequently asked questions

One layer is shifted but the rest align. What does that mean?

That layer was exported with different settings — a different origin, a mirror option, or it is a stale file from another revision. Re-export the complete set in one pass with one origin and one unit system, rather than adjusting anything in the viewer.

Why use the drill layer to check alignment?

Holes are unambiguous: every drill hit must sit centred in its pad on every copper layer it passes through, across the whole board. The drill overlay therefore localises which file disagrees with the rest.

Should I move a layer into place in Gerbv and order anyway?

No. The board house receives the files, not your adjusted view. A stack that only aligns after manual shifting is a broken export — fix the origin, units or mirroring in the CAD export and re-export the full set.

What the problem usually looks like

Three presentations cover most reports. First, the file will not load at all. Second, it loads and appears in the layer list, but the drawing area looks empty. Third, one layer shows correctly while another in the same set shows nothing. Each points a different way: failure to load suggests a format problem; loaded-but-blank suggests an empty file or a view looking elsewhere; a single blank layer suggests that layer’s export. Naming your presentation stops you applying format remedies to a zoom problem.

Cause 1: The file is not a format Gerbv views

Gerbv views three kinds of fabrication data: Gerber RS-274X files, Excellon drill files, and CSV pick-and-place files. It does not view everything inside a fabrication folder — ZIPs often also contain PDFs, drawings, BOM spreadsheets and native CAD files, none of which are Gerber layers. The other format trap is age: legacy RS-274D files, which pair drawing commands with a separate aperture file, are not supported — Gerbv supports RS-274X only, as covered in RS-274D files will not open in Gerbv. If your set is old, or was exported with an old preset, check the export format in your CAD tool before blaming the viewer. Our explainer what a Gerber file is describes how RS-274X carries its apertures and settings inside the file itself, which is precisely what RS-274D does not do.

Cause 2: The files are still inside the ZIP, or only partly extracted

A fabrication ZIP is a container, not a layer. Opening the ZIP itself, or files from inside a ZIP preview, can give an empty result because the viewer never received the real contents in a normal folder. Extract the entire archive into its own folder first, then open the extracted files — or the folder — from Gerbv. Partial extraction causes the subtler version: you extracted the copper layers and left the drill file behind, so the set looks incomplete. Extract everything, keep the set together, and only then judge what is present.

Cause 3: The extension, or the file association, is misleading you

Gerber files travel under many extensions — .gbr, .ger, layer-specific suffixes — and extensions are not a reliable guide to content. Do not dismiss a file for an unusual name; load it and let its content speak. Separately, a double-click may send the file to the wrong application because the file association points elsewhere, or nowhere. If double-clicking does nothing useful, launch Gerbv first and open the file from inside the viewer. That separates a computer association problem from a data problem in under a minute.

Cause 4: The layer really is empty — or nearly empty

Sometimes blank is accurate. An export can produce a file for a layer with no geometry: a paste layer for a side with no surface-mount parts, or a silkscreen layer enabled in the export list but never populated. Compare the file size with its siblings — a genuinely empty layer is usually dramatically smaller. If one layer is empty while the rest are healthy, check in your CAD tool that it was actually selected for plotting, and re-export the complete set in one pass so the replacement is internally consistent.

Cause 5: The board is loaded, but you are not looking at it

The most anticlimactic cause is also one of the most common. If a file uses an origin far from the board, or you previously zoomed into an empty area, the geometry can sit outside the visible canvas or as a tiny speck in a corner. Use the viewer’s fit-to-drawing view if your build provides it, or zoom out progressively and look near the origin. A related variant is scale: a file whose units were declared differently from what you assumed can render so small or large that a normal view shows nothing recognisable — that failure is treated in full in millimetres vs inches: fixing unit mismatches. As a discipline, after any load that looks blank, change the view before you change the file.

The checks, in order

1. Confirm the kind of file. Is it actually RS-274X, Excellon, or CSV data — not a PDF, drawing, or RS-274D file?
2. Extract the whole ZIP. Open files from a real extracted folder, never from inside the archive.
3. Open from inside Gerbv. Bypass double-click and any file-association problem.
4. Fit the view. Zoom out or fit to the drawing and look near the origin before concluding the layer is empty.
5. Compare siblings. Check the blank file’s size and behaviour against healthy layers from the same set.
6. Re-export the set. If one layer is genuinely empty or in the wrong format, re-export everything in one pass as RS-274X plus Excellon.

Prevention

Most blank-board episodes are prevented at export time. Keep one known-good export preset that produces RS-274X and Excellon in a single pass, always extract and inspect the exact ZIP you will send, and do a ten-second fit-the-view check on every layer before deeper inspection. When someone sends you a set that will not open, ask what tool and format produced it before exchanging screenshots — that one answer resolves a large share of cases, including every RS-274D case.

Frequently asked questions

Why does one layer open blank while the others are fine?

Usually that layer’s export was empty — the layer was enabled but had no plotted content — or the file came from a different revision. Check its size against its siblings, confirm it was selected in the plot setup, and re-export the whole set in one pass.

Can Gerbv open a fabrication ZIP directly?

Extract the ZIP into its own folder first, then open the extracted files or the folder. Opening files from inside an archive preview can make a healthy set look empty or incomplete.

My board loads but I cannot see it. Is the file corrupt?

Not necessarily. Fit the view to the drawing or zoom out and look near the origin — geometry placed far from the view, or at an unexpected scale, looks absent at normal zoom. Change the view before you change the file.