{"id":24308,"library":"pycaw","title":"pycaw","description":"Python Core Audio Windows Library - control and manage Windows audio devices, sessions, and endpoints. Current version 20251023, released annually.","status":"active","version":"20251023","language":"python","source_language":"en","source_url":"https://github.com/AndreMiras/pycaw","tags":["audio","windows","com","volume-control","core-audio"],"install":[{"cmd":"pip install pycaw","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core dependency for COM interop on Windows","package":"comtypes","optional":false}],"imports":[{"note":"AudioUtilities is in the pycaw subpackage, not directly in pycaw since v20210516 (refs #38).","wrong":"from pycaw import AudioUtilities","symbol":"AudioUtilities","correct":"from pycaw.pycaw import AudioUtilities"},{"note":"IAudioEndpointVolume is in pycaw.api.endpointvolume; direct import fails.","wrong":"from pycaw import IAudioEndpointVolume","symbol":"IAudioEndpointVolume","correct":"from pycaw.api.endpointvolume import IAudioEndpointVolume"}],"quickstart":{"code":"from pycaw.pycaw import AudioUtilities\n\ndef set_volume(volume_level):\n    devices = AudioUtilities.GetSpeakers()\n    interface = devices.Activate(\n        AudioUtilities.IID_IAudioEndpointVolume, 1, None)\n    from pycaw.api.endpointvolume import IAudioEndpointVolume\n    volume = interface.QueryInterface(IAudioEndpointVolume)\n    volume.SetMasterVolumeLevelScalar(volume_level, None)\n\nif __name__ == \"__main__\":\n    set_volume(0.5)\n    print(\"Volume set to 50%\")\n","lang":"python","description":"Set master volume to 50% using pycaw."},"warnings":[{"fix":"Use `QueryInterface(InterfaceClass)` instead of `cast(py_object, interface)`.","message":"Double free crash due to using `cast` instead of `QueryInterface` for COM interfaces. Fixed in v20240210 but code using `cast(py_object, ...)` on older versions may crash.","severity":"breaking","affected_versions":"< v20240210"},{"fix":"Change imports to `from pycaw.pycaw import AudioUtilities`.","message":"In v20210516, the `pycaw.pycaw` module was reorganized into subpackages. Code that imported `AudioUtilities` from `pycaw` directly broke.","severity":"breaking","affected_versions":">= v20210516"},{"fix":"Wrap imports with `if sys.platform == 'win32':` or use a try/except for `ModuleNotFoundError`.","message":"pycaw only works on Windows. Importing on Linux/Mac will raise `ModuleNotFoundError` for comtypes or runtime errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Update to v20230407 or later, and ensure PROPVARIANT objects are freed.","message":"Memory leaks from `PROPVARIANT` objects in older versions. Fixed in v20230407, but code that creates many `PROPVARIANT` instances without cleanup may still leak.","severity":"gotcha","affected_versions":"< v20230407"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use `from pycaw.pycaw import AudioUtilities` instead of `from pycaw import AudioUtilities`.","cause":"Wrong import path after reorganization in v20210516.","error":"ImportError: cannot import name 'AudioUtilities' from 'pycaw'"},{"fix":"Ensure you have installed pycaw (pip install pycaw) and use `from pycaw.pycaw import AudioUtilities`.","cause":"Old code trying to access pycaw submodule incorrectly or import path confusion.","error":"AttributeError: module 'pycaw' has no attribute 'pycaw'"},{"fix":"Replace `cast(ptr, POINTER(IAudioEndpointVolume))` with `interface.QueryInterface(IAudioEndpointVolume)`.","cause":"Using `cast` instead of `QueryInterface` to get an interface pointer, causing incorrect pointer handling.","error":"COMError: (-2147352559, 'Type mismatch.', (None, None, None, 0, None))"},{"fix":"Install comtypes: `pip install comtypes`. If on Linux/Mac, note that pycaw is Windows-only.","cause":"Missing comtypes dependency, or running on non-Windows platform.","error":"ModuleNotFoundError: No module named 'comtypes'"},{"fix":"Check that a playback device is enabled. Run code with admin privileges if needed.","cause":"AudioUtilities.GetSpeakers() or GetMicrophone() returned None, usually when no audio device is available or permission denied.","error":"AttributeError: 'NoneType' object has no attribute 'Activate'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}