Install & Compatibility
Where this runs
tested against v0.0.9 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.1s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pygetwindow
✓ import pygetwindow
This quickstart demonstrates how to import PyGetWindow, retrieve a list of all visible window titles and window objects, identify the active window, and find a specific window by its title. It also shows commented-out examples of how to interact with a window, such as activating, minimizing, maximizing, or resizing it.
import pygetwindow as gw
# Get a list of all visible window titles
all_titles = gw.getAllTitles()
print(f"All window titles: {all_titles}")
# Get a list of all Window objects
all_windows = gw.getAllWindows()
print(f"Number of open windows: {len(all_windows)}")
if all_windows:
# Get the currently active (foreground) window
active_window = gw.getActiveWindow()
if active_window:
print(f"\nActive window title: {active_window.title}")
print(f"Active window position: {active_window.topleft}")
print(f"Active window size: {active_window.size}")
# Try to find a specific window (e.g., a browser or editor)
# Replace 'Chrome' with a title from your `all_titles` list for testing
try:
target_window = gw.getWindowsWithTitle('Chrome')[0]
print(f"\nFound target window: {target_window.title}")
# Example actions (commented out as they affect your desktop visually)
# target_window.activate()
# target_window.minimize()
# target_window.maximize()
# target_window.restore()
# target_window.moveTo(100, 100)
# target_window.resizeTo(800, 600)
except IndexError:
print("\n'Chrome' window not found. Try another title from the list.")
Debug
Known issues
gotchaPyGetWindow's cross-platform support is currently limited. While designed to be cross-platform, full functionality is primarily implemented and tested on Windows. Support for macOS is partial, and Linux has known issues or lacks certain features. Some methods might raise exceptions or not work as expected on non-Windows systems.fixThoroughly test on your target operating system. For critical cross-platform applications, consider platform-specific fallbacks or alternative libraries with robust support for your target OS.
affects: 0.0.1 - 0.0.9
gotchaTo catch `PyGetWindowException` (e.g., when a window is not found), you must import it directly using `from pygetwindow import PyGetWindowException`. Attempting to catch `pygetwindow.PyGetWindowException` will result in a `NameError` if `pygetwindow` was imported with an alias like `import pygetwindow as gw` and `PyGetWindowException` was not explicitly imported.fixAlways use `from pygetwindow import PyGetWindowException` when you intend to catch this specific exception.
affects: All versions
gotchaThe library is still under development, and some features may be incomplete or unstable. There are reported issues such as incorrect window location coordinates (sometimes exacerbated when used with PyAutoGUI), inability to retrieve minimized windows, and problems with the `__str__` representation of `Window` objects.fixRefer to the GitHub issues for known bugs and potential workarounds. Be prepared for occasional unexpected behavior or missing functionality, especially for edge cases.
affects: All versions (0.0.1 - 0.0.9)
gotchaWindow manipulation methods like `activate()`, `minimize()`, `maximize()`, `moveTo()`, and `resizeTo()` directly interact with the operating system's GUI. They can cause visual changes on the user's screen and might interfere with user input, especially in automated scripts running in the foreground.fixUse these functions cautiously in production environments. Ensure users are aware of potential GUI interactions. Consider running automation in isolated virtual environments or during off-hours if visual interference is a concern.
affects: All versions
Upgrade
Version history
0.0.9latest on PyPI · released Oct 4, 2020
Audit
Dependencies
No dependency data recorded yet.