{"id":8782,"library":"winrt-runtime","title":"winrt-runtime","description":"winrt-runtime is the foundational Python package providing the runtime support and the `winrt.system` module for interacting with Windows Runtime (WinRT) APIs. It is part of a community-supported fork of the original pywinrt project, which provides modular bindings for individual Windows SDK namespaces (e.g., `winrt-Windows.Foundation`). The library, currently at version 3.2.1, is actively maintained with frequent updates, enabling Python developers to access a wide range of Windows OS features, hardware, and to build WinUI applications.","status":"active","version":"3.2.1","language":"en","source_language":"en","source_url":"https://github.com/pywinrt/pywinrt","tags":["windows","winrt","runtime","interop","automation","asyncio"],"install":[{"cmd":"pip install winrt-runtime","lang":"bash","label":"Base Runtime"},{"cmd":"pip install winrt-Windows.Foundation winrt-Windows.Media.SpeechSynthesis","lang":"bash","label":"Example Namespace Packages"}],"dependencies":[],"imports":[{"symbol":"Object","correct":"from winrt.system import Object"},{"symbol":"SpeechSynthesizer","correct":"from winrt.windows.media.speechsynthesis import SpeechSynthesizer"},{"note":"While aliasing works, direct import of specific classes is often preferred for clarity.","wrong":"import winrt.windows.foundation as wf; wf.Uri","symbol":"Uri","correct":"from winrt.windows.foundation import Uri"}],"quickstart":{"code":"import asyncio\nfrom winrt.system import Object\nfrom winrt.windows.media.speechsynthesis import SpeechSynthesizer\nfrom winrt.windows.media.playback import MediaPlayer, MediaPlayerAudioCategory\n\nasync def speak_hello_world():\n    synth = SpeechSynthesizer()\n    # Asynchronous operation, must be awaited\n    stream = await synth.synthesize_text_to_stream_async(\"Hello, World from WinRT!\")\n\n    media_ended_event = asyncio.Event()\n    loop = asyncio.get_running_loop()\n\n    def on_media_ended(sender: MediaPlayer, args: Object):\n        loop.call_soon_threadsafe(media_ended_event.set)\n\n    player = MediaPlayer()\n    player.audio_category = MediaPlayerAudioCategory.SPEECH\n    player.set_stream_source(stream)\n    player.add_media_ended(on_media_ended)\n\n    player.play()\n    await media_ended_event.wait()\n    print(\"Speech finished.\")\n\nif __name__ == \"__main__\":\n    # Ensure required namespace packages are installed: \n    # pip install winrt-Windows.Media.SpeechSynthesis winrt-Windows.Media.Playback\n    asyncio.run(speak_hello_world())\n","lang":"python","description":"This quickstart demonstrates how to use `winrt-runtime` along with specific WinRT namespace packages to synthesize and play speech. It utilizes asynchronous WinRT APIs with Python's `asyncio`. Make sure to install `winrt-Windows.Media.SpeechSynthesis` and `winrt-Windows.Media.Playback` for this example to run."},"warnings":[{"fix":"Instead of `pip install winrt` or `pip install winsdk`, install `winrt-runtime` for the base runtime and then `pip install winrt-Windows.MyNamespace` for each specific WinRT namespace you need. Update imports from `winsdk.windows.some_module` or `winrt.windows.some_module` to `from winrt.windows.some_module import SomeClass`.","message":"Starting with v3.0.0, the Python WinRT bindings transitioned from monolithic `winrt` or `winsdk` packages to a modular distribution. Each WinRT namespace (e.g., `Windows.Foundation`, `Windows.Media.SpeechSynthesis`) now requires its own `winrt-Windows.Namespace` package installation.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Migrate to `winrt-runtime` and the specific `winrt-Windows.*` namespace packages. This involves adjusting both installation commands and import statements.","message":"The `winsdk` package, which was a community-maintained fork after the original `winrt` package, is now deprecated in favor of the modular `winrt-runtime` and `winrt-Windows.*` package structure.","severity":"deprecated","affected_versions":"All `winsdk` versions"},{"fix":"Always `await` WinRT asynchronous methods (those ending with `_async`). For events that signal completion (like `MediaEnded`), use `asyncio.Event` and ensure callbacks are scheduled on the event loop with `loop.call_soon_threadsafe`.","message":"WinRT APIs often involve asynchronous operations, which require proper integration with Python's `asyncio` event loop. Incorrect handling can lead to blocking or unexpected behavior.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `winrt-runtime` for the core functionality and then install specific namespace packages like `winrt-Windows.Foundation` for the APIs you need: `pip install winrt-runtime winrt-Windows.MyNamespace`.","cause":"This error typically indicates that you are attempting to install the old, monolithic `winrt` package which may not be available for your Python version (e.g., Python 3.10+) or has been superseded by the modular `winrt-runtime` approach.","error":"ERROR: Could not find a version that satisfies the requirement winrt (from versions: none)"},{"fix":"Install the required namespace package: `pip install winrt-Windows.Devices.Geolocation`.","cause":"You have likely installed `winrt-runtime` but have not installed the specific PyPI package for the `Windows.Devices.Geolocation` namespace.","error":"ModuleNotFoundError: No module named 'winrt.windows.devices.geolocation'"},{"fix":"Ensure WinRT objects are kept alive for the duration of their use. For `asyncio` operations, ensure the event loop is running and that operations are properly awaited. For specific problematic APIs, check for newer versions of `winrt-runtime` or the relevant `winrt-Windows.*` package, as bug fixes are ongoing (e.g., `asyncio` cancellation propagation in v3.2.0).","cause":"This generic `RuntimeError` can occur when a WinRT object is accessed after its underlying COM object has been released or shut down, often due to improper lifecycle management, especially with objects tied to UI threads or background tasks. In some cases, it can also stem from an unhandled `asyncio` issue in older versions of `winrt` when trying to access hardware-related APIs like geolocation.","error":"RuntimeError: The object has been shut down."}]}