Install & Compatibility
Where this runs
tested against v4.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 4.2s
py 3.11
✕ build_error
✓ 4.1s
py 3.12
✕ build_error
✓ 4.03s
py 3.13
✕ build_error
✓ 4.13s
py 3.9
✕ build_error
3/4 runs
177MB installed
● package 177MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AbsolutePoseEstimationOptions
✓ from pycolmap import AbsolutePoseEstimationOptions
✗ from pycolmap import Sfm
This quickstart demonstrates the high-level `pycolmap.Sfm` class to run a full Structure-from-Motion pipeline. It creates dummy images and attempts a reconstruction, which is expected to fail with only two random images, but illustrates the basic API usage.
import os
import pycolmap
import numpy as np
from PIL import Image
# Create a dummy image directory
image_dir = "pycolmap_quickstart_images"
output_dir = "pycolmap_quickstart_output"
os.makedirs(image_dir, exist_ok=True)
os.makedirs(output_dir, exist_ok=True)
# Create two dummy images (COLMAP typically needs more and with overlap)
img_size = (100, 100)
for i in range(2):
dummy_image = Image.fromarray(np.random.randint(0, 255, img_size + (3,), dtype=np.uint8))
dummy_image.save(os.path.join(image_dir, f"image_{i+1:02d}.jpg"))
print(f"Dummy images created in {image_dir}")
# Run the high-level SfM reconstruction
# Note: With only two random images, this is expected to fail or produce an empty model.
# A real scenario requires actual images with sufficient overlap and features.
try:
sfm_pipeline = pycolmap.Sfm(image_dir, output_dir)
reconstruction = sfm_pipeline.run()
if reconstruction:
print(f"Reconstruction successful! Found {len(reconstruction.images)} images and {len(reconstruction.points3D)} 3D points.")
else:
print("Reconstruction did not produce a valid model (expected for random, non-overlapping images).")
except Exception as e:
print(f"Reconstruction failed (expected for random images without overlap/features): {e}")
# Optional: Clean up created directories
# import shutil
# shutil.rmtree(image_dir, ignore_errors=True)
# shutil.rmtree(output_dir, ignore_errors=True)
Debug
Known issues
gotchaInstallation of `pycolmap[cuda]` (for GPU support) requires a CUDA Toolkit version that is compatible with COLMAP's C++ build. Incompatibilities between CUDA Toolkit, NVIDIA drivers, and `pycolmap` can lead to runtime errors or prevent GPU acceleration from being utilized.fixConsult the COLMAP documentation for supported CUDA versions. Ensure your CUDA Toolkit and GPU drivers are up-to-date and compatible with the `pycolmap` wheel you are installing.
affects: All versions with CUDA support
gotchaBuilding `pycolmap` from source is highly complex due to its extensive C++ dependencies (e.g., Ceres, Boost, Eigen, SuiteSparse). Using the pre-built wheels (`pip install pycolmap`) is strongly recommended to avoid intricate build environment issues.fixPrefer installing via `pip install pycolmap` using pre-built wheels. If building from source is necessary, refer to the detailed COLMAP C++ build instructions and `pycolmap` specific build steps on its GitHub repository.
affects: All versions
gotchaMismatched `numpy` versions can lead to ABI compatibility errors (e.g., `ValueError: numpy.ndarray size changed`, `ImportError` related to `_multiarray_umath`), especially with C++ extensions like `pycolmap`. This happens when `pycolmap` is compiled against a different NumPy ABI than the one currently installed.fixEnsure `numpy` is up-to-date and compatible with your `pycolmap` installation. Try reinstalling both `numpy` and `pycolmap` in a clean virtual environment: `pip install --upgrade numpy` then `pip install pycolmap`.
affects: All versions
Upgrade
Version history
4.0.4latest on PyPI · released Apr 27, 2026
Audit
Dependencies
numpyrequiredFundamental for numerical operations and array handling.
scipyrequiredUsed for scientific computing and various algorithms.