{"id":24483,"library":"pywinctl","title":"PyWinCtl","description":"PyWinCtl is a cross-platform Python library (Windows, macOS, Linux with X11/Wayland) for getting information about and controlling on-screen windows. Version 0.4.1 supports Python 3.9+ and provides window enumeration, activation, resizing, moving, and property retrieval. Release cadence is irregular, with major features added every few months.","status":"active","version":"0.4.1","language":"python","source_language":"en","source_url":"https://github.com/Kalmat/PyWinCtl","tags":["window-management","cross-platform","gui-automation","desktop"],"install":[{"cmd":"pip install pywinctl","lang":"bash","label":"Default install from PyPI"}],"dependencies":[{"reason":"Core dependency for basic window management","package":"pygetwindow","optional":false},{"reason":"Used for rectangle geometry operations","package":"pyrect","optional":false},{"reason":"Multi-monitor support (added in v0.0.50)","package":"pymonctl","optional":false}],"imports":[{"note":"PyWinCtl is the library name, not a class; use module-level functions and the Window class.","wrong":"from pywinctl import PyWinCtl","symbol":"PyWinCtl","correct":"import pywinctl as pwc"},{"note":"Window objects are returned by functions like getAllWindows(), getActiveWindow(), etc. They are not instantiated directly.","wrong":"from pywinctl import Window; win = Window()","symbol":"Window","correct":"import pywinctl; win = pywinctl.getAllWindows()[0]"},{"note":"The function is named getAllWindows; getWindows does not exist.","wrong":"import pywinctl; pywinctl.getWindows()","symbol":"getAllWindows","correct":"import pywinctl; pywinctl.getAllWindows()"}],"quickstart":{"code":"import pywinctl\n\n# Get all windows\nwindows = pywinctl.getAllWindows()\nfor win in windows:\n    print(f'{win.title}: {win.bbox}')\n\n# Get active window\nactive = pywinctl.getActiveWindow()\nif active:\n    print('Active window title:', active.title)\n\n# Move and resize window\nwin = windows[0]\nwin.moveTo(100, 100)\nwin.resizeTo(800, 600)\n\n# Check if window is visible\nprint('Visible:', win.isVisible)","lang":"python","description":"Basic usage: enumerate windows, get active window, move/resize."},"warnings":[{"fix":"os.environ['PYWNCTL_WAYLAND_UNSAFE'] = '1' before importing pywinctl.","message":"On Linux with Wayland, getActiveWindow() may return None unless 'unsafe mode' is enabled. Enable by setting environment variable PYWNCTL_WAYLAND_UNSAFE=1 before import.","severity":"gotcha","affected_versions":">=0.1,<=0.4.0"},{"fix":"Use getMonitor() instead of getDisplay().","message":"The method getDisplay() is deprecated in v0.4 and replaced by getMonitor().","severity":"deprecated","affected_versions":"0.4.0"},{"fix":"Use the standard pywinctl API; class MacOSNSWindow no longer exists.","message":"MacOS: MacOSNSWindow was removed in v0.4. All window operations now use AppleScript. Code that directly references MacOSNSWindow will break.","severity":"breaking","affected_versions":"0.4.0 and later"},{"fix":"Always convert to int: win.moveTo(int(x), int(y)).","message":"Window.moveTo() and resizeTo() expect integer coordinates. Passing floats may cause silent failure or unexpected behavior.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use 'import pywinctl' and then call functions like pywinctl.getAllWindows().","cause":"Attempting to import 'PyWinCtl' as a class when it is the module name.","error":"AttributeError: module 'pywinctl' has no attribute 'PyWinCtl'"},{"fix":"Check if the result is None before iterating: windows = pywinctl.getAllWindows() or []","cause":"getAllWindows() returns None on unsupported platforms or if the backend fails.","error":"TypeError: 'NoneType' object is not iterable"},{"fix":"Run the script with elevated permissions (admin) or target windows that allow external control.","cause":"On Windows, trying to manipulate a window owned by another process (e.g., UIPI) without proper privileges.","error":"OSError: [WinError 5] Access is denied"},{"fix":"Use the public API: 'import pywinctl' and let the library handle the backend selection.","cause":"Trying to import internal submodules directly; they are platform-specific and not intended for direct use.","error":"ModuleNotFoundError: No module named 'pywinctl._pywinctl_osx'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}