---
id: fill-voids
version: "2.1.2"
license: LGPL-3.0-or-later
license_treatment: copyleft
maintenance: active
---

# fill-voids — Fill voids in 3D binary images fast.

License: copyleft · Maintenance: active · Downloads: 113.0K/mo

## What it is and what it does

fill-voids is a Python library that fills interior holes in binary images using a fast scan-line flood-fill algorithm. It works on both 2D and 3D arrays and is designed to be significantly faster and more memory-efficient than scipy's binary_fill_holes, which uses slower serial dilations. The library is written in C++ with Python bindings, and it exposes both a Python API and a C++ header for direct use.

The algorithm marks foreground pixels, scans from image boundaries to identify background regions connected to the exterior, then flood-fills those regions. Everything not visited by the flood fill is marked as foreground, effectively filling all interior voids. It uses performance tricks like libdivide for coordinate computation and directional scanning to exploit memory locality. The package is actively maintained, supports Python 3.10, 3.11, and 3.12 with prebuilt wheels, and has no known security vulnerabilities.

Use it for:

- Cleaning up connectomics segmentation masks by filling small holes in labeled regions before downstream analysis.
- Preprocessing binary medical images to remove noise artifacts before feature extraction or registration.
- Morphological post-processing in computer vision pipelines where speed matters on large 3D volumetric data.
- Filling voids in 2D binary masks for image segmentation refinement in scientific imaging workflows.
- Real-time or batch processing of densely labeled 3D datasets where scipy's performance is a bottleneck.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Fills interior voids in 2D and 3D binary images using a fast flood-fill algorithm, designed as a higher-performance alternative to scipy.ndimage.binary_fill_holes.

Yes, if you work with binary image morphology and need better performance than scipy.ndimage.binary_fill_holes. The package is actively maintained, has no vulnerabilities, and offers prebuilt wheels for common platforms. The LGPL-3.0-or-later license is permissive for research and open-source use but requires derivative works to remain open; verify compatibility with your project's licensing model. Medium install friction is acceptable for the performance gain in image processing workflows.

## Install

pip install fill-voids
uv add fill-voids
poetry add fill-voids

## Installing fill-voids

Before you install: Medium install friction due to compiled C++ components; prebuilt wheels available for Python 3.10, 3.11, and 3.12 on macOS, Linux (manylinux, musllinux), and Windows. Falls back to source build if no wheel matches your platform, requiring a C++ compiler and python3-dev headers.

License in practice: Licensed under LGPL-3.0-or-later (copyleft). Derivative works and modifications must be released under compatible terms; static linking or closed-source use requires explicit permission or relicensing.

Quickstart:

import fill_voids
import numpy as np

img = np.zeros((512, 512), dtype=np.uint8)
filled = fill_voids.fill(img, in_place=False)
filled, N = fill_voids.fill(img, return_fill_count=True)

Requires numpy and fastremap as runtime dependencies; C++ compiler needed if installing from source on unsupported platforms.

Verify before relying:

- Performance improvement magnitude vs. scipy.ndimage.binary_fill_holes on typical workloads
- Memory overhead of in_place=False mode on large images
- Whether Python 3.9 and 3.13 are supported at runtime despite classifier presence

## Package facts

- License: LGPL-3.0-or-later (copyleft)
- Python support: unspecified
- Install friction: medium
- Maintenance: active
- Downloads: 113.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

binary image hole filling, void filling 3d images, flood fill algorithm, morphological image processing, connectomics segmentation, fast binary morphology, image inpainting voids, image-processing, morphology, high-performance

[View on SkillFed](https://skillfed.io/packages/fill-voids) · [View on PyPI](https://pypi.org/project/fill-voids/)