Install & Compatibility
Where this runs
tested against v0.4.1 · 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 · 21MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.000s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PyWinCtl
✓ import pywinctl as pwc
✗ from pywinctl import PyWinCtl
PyWinCtl is the library name, not a class; use module-level functions and the Window class.
Window
✓ import pywinctl; win = pywinctl.getAllWindows()[0]
✗ from pywinctl import Window; win = Window()
Window objects are returned by functions like getAllWindows(), getActiveWindow(), etc. They are not instantiated directly.
getAllWindows
✓ import pywinctl; pywinctl.getAllWindows()
✗ import pywinctl; pywinctl.getWindows()
The function is named getAllWindows; getWindows does not exist.
Basic usage: enumerate windows, get active window, move/resize.
import pywinctl
# Get all windows
windows = pywinctl.getAllWindows()
for win in windows:
print(f'{win.title}: {win.bbox}')
# Get active window
active = pywinctl.getActiveWindow()
if active:
print('Active window title:', active.title)
# Move and resize window
win = windows[0]
win.moveTo(100, 100)
win.resizeTo(800, 600)
# Check if window is visible
print('Visible:', win.isVisible)
Errors
Common errors & fixes
AttributeError: module 'pywinctl' has no attribute 'PyWinCtl'
Attempting to import 'PyWinCtl' as a class when it is the module name.
fixUse 'import pywinctl' and then call functions like pywinctl.getAllWindows().
TypeError: 'NoneType' object is not iterable
getAllWindows() returns None on unsupported platforms or if the backend fails.
fixCheck if the result is None before iterating: windows = pywinctl.getAllWindows() or []
OSError: [WinError 5] Access is denied
On Windows, trying to manipulate a window owned by another process (e.g., UIPI) without proper privileges.
fixRun the script with elevated permissions (admin) or target windows that allow external control.
ModuleNotFoundError: No module named 'pywinctl._pywinctl_osx'
Trying to import internal submodules directly; they are platform-specific and not intended for direct use.
fixUse the public API: 'import pywinctl' and let the library handle the backend selection.
Upgrade
Version history
0.4.1latest on PyPI · released Sep 23, 2024
Audit
Dependencies
pygetwindowrequiredCore dependency for basic window management
pyrectrequiredUsed for rectangle geometry operations
pymonctlrequiredMulti-monitor support (added in v0.0.50)