Fix BlenderGIS “No ImageIO” Error: Manual Freeimage Library Fix
You install BlenderGIS, tick the checkbox to enable it, and Blender throws an error about imageio or freeimage — the addon refuses to load. This is one of the most common first-run failures for new BlenderGIS users, and it has nothing to do with your Blender setup. Here’s exactly what’s wrong and how to fix it in a few minutes.
Quick answer: On first run, BlenderGIS tries to download the freeimage native library (used by the imageio package to read basemap tiles) from the internet. If the download fails — no connection, a proxy, a firewall, or an offline machine — the addon can’t start. Fix it by downloading the freeimage binaries yourself and copying them into BlenderGIS/core/lib/imageio/resources/freeimage/, then restarting Blender. Mac ARM (Apple Silicon) users should use BlenderGIS v2.2.10 or later.
Why the “No ImageIO” Error Happens
BlenderGIS needs to read image tiles from web map services (satellite basemaps, elevation previews, and similar). For that it bundles imageio, a Python imaging library, which in turn relies on a native binary called freeimage to decode common formats like JPEG and PNG.
Because freeimage is a compiled binary — different for Windows, macOS (Intel vs. ARM), and Linux — the addon does not ship it inside the ZIP. Instead, the official behavior documented on the BlenderGIS wiki is:
- On first startup, BlenderGIS checks whether the freeimage binary exists in its
resources/freeimage/folder. - If missing, it attempts to download the correct build for your OS automatically.
- If the download fails — no internet, a corporate proxy, a firewall blocking the host, or an air-gapped machine — you get the imageio/freeimage error and the addon won’t enable.
So the error is really telling you: “I couldn’t fetch my image-reading library.” The addon itself is fine; the missing piece is a single folder of binaries.
The Fix: Manually Install the Freeimage Library
Follow these steps exactly. The folder layout matters — one misplaced file and the error persists.
Step 1 — Find your BlenderGIS addon folder
Locate where the addon is installed. Typical paths:
- Windows:
%APPDATA%\Blender Foundation\Blender\<version>\scripts\addons\BlenderGIS - macOS:
~/Library/Application Support/Blender/<version>/scripts/addons/BlenderGIS - Linux:
~/.config/blender/<version>/scripts/addons/BlenderGIS
Step 2 — Create (or find) the freeimage resources folder
Inside the addon folder, navigate to core/lib/imageio/resources/. Create a subfolder named freeimage if it doesn’t exist, so the full path is:
BlenderGIS/core/lib/imageio/resources/freeimage/
Step 3 — Download the freeimage binaries for your OS
Download the freeimage binary matching your operating system from the imageio project’s binary distribution (the imageio project hosts platform-specific freeimage builds; search “imageio freeimage binary download” for the current host, or grab them from a machine where BlenderGIS downloaded them successfully). Place the downloaded file(s) directly inside the freeimage/ folder you created.
Step 4 — Restart Blender and re-enable BlenderGIS
Fully quit Blender (not just close the window), reopen it, go to Edit > Preferences > Add-ons, and enable BlenderGIS. With the binaries in place, the addon no longer needs to download anything and should activate cleanly. If you run into trouble during installation itself, our BlenderGIS installation guide covers the full process.
Corporate / offline machines: If your computer has no internet at all, download the freeimage binaries on another machine and transfer them via USB. BlenderGIS only needs the files in that folder — it never phones home again for this purpose.
Still Not Working? Check These
Mac ARM (Apple Silicon) users, check this first. Older BlenderGIS releases predate the ARM64 build of the freeimage library, so even a successful automatic download could hand you an incompatible binary. BlenderGIS v2.2.10 (released May 2024) added support for the ARM64 freeimage build — if you’re seeing the imageio error on an M1/M2/M3/M4 Mac, make sure you’re running v2.2.10 or later (the current release is v2.2.15, December 2025). Download the latest ZIP from the official domlysz/BlenderGIS GitHub releases page, reinstall, and apply the manual freeimage fix above if the automatic download still fails. Intel Mac users are unaffected by this particular issue.
- Blender version compatibility. BlenderGIS requires Blender v2.83 or newer and officially supports the 4.x and 5.x series. Running a much older Blender can produce misleading dependency errors.
- Proxy settings. If you’re behind a corporate proxy, configure it at the OS level before Blender’s first run so the automatic download can succeed — or skip straight to the manual method.
- Antivirus / firewall. Some security software quarantines freshly downloaded native binaries. If BlenderGIS worked once and then broke after a reboot, check your antivirus quarantine for the freeimage files.
- Permissions. On Linux and macOS, make sure the addon folder is writable by your user account; otherwise the automatic download fails silently with a permission error instead of a network error.
For a broader map of common BlenderGIS problems, see the BlenderGIS troubleshooting hub.
Frequently Asked Questions
What exactly is the freeimage library?
Freeimage is an open-source native (compiled C/C++) library for reading and writing image formats like JPEG, PNG, and TIFF. BlenderGIS uses it through the imageio Python package to decode basemap tiles and other imagery. Because it’s a compiled binary, a different build is needed for each operating system and CPU architecture.
Why doesn’t the BlenderGIS ZIP include freeimage?
Shipping every platform’s native binary inside the addon ZIP would bloat the download for everyone. Instead, BlenderGIS downloads only the build matching your OS on first run — and the manual fix in this guide covers the cases where that automatic download can’t happen.
I’m on Windows and the error appeared behind a firewall. What’s the fastest fix?
Use the manual method: download the Windows freeimage binary on any internet-connected machine, copy it into BlenderGIS/core/lib/imageio/resources/freeimage/ in your Blender addons folder, and restart Blender. It takes about two minutes and bypasses the firewall entirely.
Does the freeimage fix apply to Blender 4.x and 5.x?
Yes. The freeimage dependency is independent of the Blender version — it matters which OS and CPU architecture you’re on, not which Blender release. Just make sure your BlenderGIS version supports your Blender: v2.83+ minimum, with 4.x and 5.x supported by recent releases.
I have an M1 Mac and installed the latest BlenderGIS but still get the error. Why?
Double-check you’re actually on v2.2.10 or newer (current is v2.2.15) — older ZIPs lingering in your downloads are a common cause. If the version is right and the automatic download still fails, do the manual copy; the ARM64 freeimage binary works once it’s in the resources folder.
Will I need to redo this after every BlenderGIS update?
Usually not. The freeimage folder lives inside the addon directory, so reinstalling BlenderGIS from a fresh ZIP replaces it — in that case, copy the binaries over again. Updating in place (without deleting the addon folder) preserves them.