pycaw

20251023 verified Fri May 01 auth: no python

Python Core Audio Windows Library - control and manage Windows audio devices, sessions, and endpoints. Current version 20251023, released annually.

pip install pycaw

Common errors

error ImportError: cannot import name 'AudioUtilities' from 'pycaw' ↓

cause Wrong import path after reorganization in v20210516.

fix

Use from pycaw.pycaw import AudioUtilities instead of from pycaw import AudioUtilities.

error AttributeError: module 'pycaw' has no attribute 'pycaw' ↓

cause Old code trying to access pycaw submodule incorrectly or import path confusion.

fix

Ensure you have installed pycaw (pip install pycaw) and use from pycaw.pycaw import AudioUtilities.

error COMError: (-2147352559, 'Type mismatch.', (None, None, None, 0, None)) ↓

cause Using `cast` instead of `QueryInterface` to get an interface pointer, causing incorrect pointer handling.

fix

Replace cast(ptr, POINTER(IAudioEndpointVolume)) with interface.QueryInterface(IAudioEndpointVolume).

error ModuleNotFoundError: No module named 'comtypes' ↓

cause Missing comtypes dependency, or running on non-Windows platform.

fix

Install comtypes: pip install comtypes. If on Linux/Mac, note that pycaw is Windows-only.

error AttributeError: 'NoneType' object has no attribute 'Activate' ↓

cause AudioUtilities.GetSpeakers() or GetMicrophone() returned None, usually when no audio device is available or permission denied.

fix

Check that a playback device is enabled. Run code with admin privileges if needed.

Warnings

breaking 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. ↓

fix Use `QueryInterface(InterfaceClass)` instead of `cast(py_object, interface)`.

breaking In v20210516, the `pycaw.pycaw` module was reorganized into subpackages. Code that imported `AudioUtilities` from `pycaw` directly broke. ↓

fix Change imports to `from pycaw.pycaw import AudioUtilities`.

gotcha pycaw only works on Windows. Importing on Linux/Mac will raise `ModuleNotFoundError` for comtypes or runtime errors. ↓

fix Wrap imports with `if sys.platform == 'win32':` or use a try/except for `ModuleNotFoundError`.

gotcha Memory leaks from `PROPVARIANT` objects in older versions. Fixed in v20230407, but code that creates many `PROPVARIANT` instances without cleanup may still leak. ↓

fix Update to v20230407 or later, and ensure PROPVARIANT objects are freed.

Imports

AudioUtilities
wrong
```
from pycaw import AudioUtilities
```
correct
```
from pycaw.pycaw import AudioUtilities
```
AudioUtilities is in the pycaw subpackage, not directly in pycaw since v20210516 (refs #38).
IAudioEndpointVolume
wrong
```
from pycaw import IAudioEndpointVolume
```
correct
```
from pycaw.api.endpointvolume import IAudioEndpointVolume
```
IAudioEndpointVolume is in pycaw.api.endpointvolume; direct import fails.

Quickstart

Set master volume to 50% using pycaw.

from pycaw.pycaw import AudioUtilities

def set_volume(volume_level):
    devices = AudioUtilities.GetSpeakers()
    interface = devices.Activate(
        AudioUtilities.IID_IAudioEndpointVolume, 1, None)
    from pycaw.api.endpointvolume import IAudioEndpointVolume
    volume = interface.QueryInterface(IAudioEndpointVolume)
    volume.SetMasterVolumeLevelScalar(volume_level, None)

if __name__ == "__main__":
    set_volume(0.5)
    print("Volume set to 50%")