pywinrm

pywinrm is a Python client for Windows Remote Management (WinRM), the SOAP-based protocol Windows machines expose for remote management. It lets any machine that can run Python — Linux, macOS, or Windows — open a shell on a target Windows host, run arbitrary commands or PowerShell scripts, and read back stdout, stderr, and status codes, without needing a native Windows client.

The library ships both a high-level Session API for one-shot command and PowerShell execution, and a lower-level Protocol/Transport API for callers that need to manage shells and commands explicitly across multiple calls. It supports basic, certificate, NTLM, Kerberos, CredSSP, and SSL-wrapped transports, plus optional message-level encryption for authentication methods that support it, so callers can talk to WinRM endpoints securely even without HTTPS.

pywinrm is best known as the WinRM connection layer inside Ansible, where it is the standard way Ansible manages Windows hosts, but it works equally well as a standalone library for any Python-based orchestration, provisioning, or remote-administration tool that needs to drive Windows machines.

What You Get

• A Session class that opens a WinRM connection and runs shell commands or PowerShell scripts with a single call, returning a Response with stdout, stderr, and status code
• A lower-level Protocol/Transport API for explicit shell/command lifecycle management (open_shell, run_command, get_command_output, cleanup_command, close_shell)
• Support for basic, certificate, NTLM, Kerberos, CredSSP, and SSL transports, selectable per-session
• Automatic base64/UTF-16LE encoding of PowerShell scripts and CLIXML-to-plain-text error message translation
• Optional message-level encryption (auto/always/never) for NTLM, Kerberos, and CredSSP transports independent of the HTTP transport layer
• Endpoint URL auto-detection that fills in scheme, port, and the /wsman path from a bare hostname

Common Use Cases

• Driving Windows hosts from Ansible (pywinrm is Ansible’s underlying WinRM connection plugin)
• Running provisioning or configuration-management scripts against Windows servers from a Linux or macOS control node
• Fetching WMI data or running diagnostic PowerShell scripts across a fleet of remote Windows machines
• Building custom Python automation/orchestration tools that need to execute remote commands on Windows without RDP or a native agent

Under The Hood

Architecture pywinrm is a small, cleanly layered library: winrm/__init__.py exposes the high-level Session and Response classes for one-shot command/PowerShell execution, winrm/protocol.py’s Protocol class implements the WinRM SOAP operations (open_shell, run_command, get_command_output, cleanup_command, close_shell) by building and parsing XML envelopes, and winrm/transport.py’s Transport class owns the actual HTTP calls and auth-method selection (basic, certificate, NTLM, Kerberos, CredSSP, SSL) on top of requests. winrm/encryption.py sits between Transport and the wire, wrapping/unwrapping message bodies when message-level encryption is active, and winrm/exceptions.py defines a small typed hierarchy (WinRMError, WSManFaultError, WinRMTransportError, WinRMOperationTimeoutError, AuthenticationError) that callers can catch selectively. There is no plugin system or dependency injection here — it is a straightforward request/response client where each layer has one clear job, and a vendored, unmaintained fork of requests_kerberos is bundled under winrm/vendor/ to keep Kerberos support working without depending on an external package.

Tech Stack The library targets Python 3.8+ and depends on requests for HTTP, requests_ntlm for NTLM auth, and xmltodict for parsing WSMan XML responses; CredSSP and Kerberos support are optional extras (requests-credssp, pykerberos/winkerberos) declared in pyproject.toml. The project builds via a PEP 517-compliant setuptools backend with the version read dynamically from winrm.__version__, is fully type-annotated with a py.typed marker for downstream type checkers, and is formatted/linted with black, isort, and mypy in strict mode (disallowing untyped defs and implicit re-exports).

Code Quality The winrm/tests/ package is substantial for the library’s size, covering the transport layer, encryption wrapping/unwrapping, protocol-level exceptions, and session behavior with pytest, plus a separate integration test file gated behind a live WinRM endpoint. Error handling is explicit and typed rather than swallowed — WSMan faults are parsed into structured fields (fault code, subcode, WMI error code) instead of surfacing a raw HTTP error, and operation timeouts are distinguished from connection timeouts as a distinct, intentionally-retryable exception. CI runs the test suite and a black --check formatting gate across Linux, macOS, and Windows on multiple CPython and PyPy versions.

What Makes It Unique pywinrm’s differentiator isn’t a novel abstraction but breadth and correctness of WinRM’s authentication matrix — basic, certificate, NTLM, Kerberos, CredSSP, and SSL are all implemented against the same session API, including CredSSP’s double-hop authentication and transport-independent message encryption that layers GSS-API wrap/unwrap on top of NTLM, Kerberos, or CredSSP even over plain HTTP. That combination is what makes it Ansible’s de facto Windows connection plugin: it is one of the few Python libraries that faithfully reproduces the full set of auth options a real WinRM deployment can be configured with.