Install & Compatibility
Where this runs
tested against v0.3.0 · 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.9
✕ build_error
✓ 6.53s
128MB installed
● package 128MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dxcam
✓ import dxcam
✗ import dxcam
This quickstart initializes DXcam, starts capturing, grabs a single frame, and displays it using OpenCV (if installed). It includes error handling for non-Windows environments and initialization failures.
import dxcam
import cv2
# dxcam is Windows-only, so this example will only run there.
# On other OS, it will raise a RuntimeError.
try:
# Create a DXcam instance, auto-detecting the primary display output.
# Optionally specify output_idx, region, or device_idx.
camera = dxcam.create()
if camera is None:
print("Failed to create DXcam instance. Ensure a display is connected and drivers are up to date.")
else:
# Start capturing frames. By default, it captures the full screen.
camera.start(target_fps=30)
# Grab a single frame
frame = camera.grab()
if frame is not None:
print(f"Captured frame with shape: {frame.shape}, dtype: {frame.dtype}")
# Example: Display the frame using OpenCV (requires opencv-python)
cv2.imshow('DXcam Frame', frame)
cv2.waitKey(1000) # Display for 1 second
cv2.destroyAllWindows()
else:
print("Failed to grab a frame.")
# Stop capturing frames when done
camera.stop()
except RuntimeError as e:
print(f"Error initializing DXcam: {e}. DXcam is a Windows-only library.")
except ImportError as e:
print(f"Missing required dependency for quickstart: {e}. Try 'pip install dxcam opencv-python numpy'.")
Debug
Known issues
gotchaDXcam is a Windows-only library. Attempting to import or use it on other operating systems will result in a RuntimeError.fixEnsure your development and deployment environment is Windows. Consider conditional imports or platform checks if your application needs to support multiple OS.
affects: All versions
breakingVersion 0.1.0 introduced a 'Major overhaul', switching the default capture path to `IDXGIOutput5.DuplicateOutput1` and changing frame transfer from `CopyResource` to `CopySubresourceRegion`. This may alter performance characteristics or reveal new issues if upgrading from pre-0.1.0 versions, especially for applications sensitive to low-level capture behavior.fixThoroughly test performance and stability when migrating from versions prior to 0.1.0. Monitor for `DXGI_ERROR_DEVICE_REMOVED` or unexpected frame drops.
affects: <0.1.0 to >=0.1.0
gotchaVersion 0.2.0 introduced a WinRT backend and new processor splits (cv2 backend / numpy Cython-kernel backend). While this adds flexibility, users relying on specific performance profiles from earlier versions might need to re-evaluate their chosen backend/processor for optimal results.fixConsult the DXcam documentation to understand the different backends and processors. Experiment with `processor='numpy_kernels'` or `processor='cv2'` (if `opencv-python` is installed) and different `backend` options to find the best fit for your use case.
affects: >=0.2.0
gotchaDXcam relies on the Desktop Duplication API, which can encounter 'device lost' scenarios (e.g., monitor unplugged, GPU driver reset, display mode change). While DXcam attempts to recover, persistent issues can lead to `None` frames or crashes.fixImplement robust error handling for `None` frames returned by `grab()`. Consider re-initializing the DXcam instance if errors persist or if the display configuration changes significantly. Version 0.3.0 improved handling of DXGI mode switches, but device removal remains a challenge.
affects: All versions
Upgrade
Version history
0.3.0latest on PyPI · released Mar 12, 2026
Audit
Dependencies
numpyrequiredUsed for efficient array manipulation of captured frames; essential for many processing backends.
opencv-pythonoptionalCommonly used for image processing with captured frames, and one of DXcam's processor backends.