Registry / devops / pywinrm

pywinrm

JSON →
library0.5.0pypypi✓ verified 26d ago

pywinrm is a Python library that enables remote execution of commands on Windows machines using the Windows Remote Management (WinRM) protocol. It supports various authentication mechanisms like Basic, NTLM, and Kerberos, and allows running both CMD and PowerShell commands. The current stable version is 0.5.0, with updates occurring periodically to address bugs and improve compatibility.

pip install pywinrm
INSTALL
IMPORT
SIG · PYWINRM
P
pywinrm
devopspythonv0.5.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
1/2 runs
1/2 runs
py 3.11
1/2 runs
1/2 runs
py 3.12
1/2 runs
1/2 runs
py 3.13
1/2 runs
1/2 runs
py 3.9
1/2 runs
1/2 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Session
from winrm import Session
from pywinrm import Session
Despite the package being `pywinrm`, the top-level module to import is `winrm`.
Protocol
from winrm import Protocol
Used for lower-level WinRM protocol interactions if needed.

This quickstart demonstrates how to establish a WinRM session using environment variables for credentials and execute both a simple command-line command (`run_cmd`) and a PowerShell command (`run_ps`). It also shows how to access the standard output, standard error, and exit code from the command results.

import winrm import os # Configure target details using environment variables for security/flexibility target_host = os.environ.get('WINRM_HOST', 'localhost') target_port = os.environ.get('WINRM_PORT', '5985') # 5985 for HTTP, 5986 for HTTPS username = os.environ.get('WINRM_USERNAME', 'Administrator') password = os.environ.get('WINRM_PASSWORD', 'Password123!') # Use a strong password! # Establish a WinRM session # For HTTPS, change the URL prefix to 'https' and consider 'verify_ssl_certs=False' # if using self-signed certificates (use with caution in production). session = winrm.Session( f'http://{target_host}:{target_port}/wsman', auth=(username, password) ) # Execute a simple command print(f"Running 'hostname' on {target_host}...") result = session.run_cmd('hostname') print(f"Stdout: {result.std_out.decode('utf-8').strip()}") print(f"Stderr: {result.std_err.decode('utf-8').strip()}") print(f"Exit Code: {result.status_code}") # Execute a PowerShell command print("\nRunning 'Get-Service' PowerShell command...") ps_result = session.run_ps('Get-Service Spooler | Select-Object Name, Status') print(f"Stdout: {ps_result.std_out.decode('utf-8').strip()}") print(f"Stderr: {ps_result.std_err.decode('utf-8').strip()}") print(f"Exit Code: {ps_result.status_code}")
Debug
Known issues
gotchaThe package installed via pip is `pywinrm`, but the module to import in your Python code is `winrm`. Forgetting this leads to `ModuleNotFoundError`.
fix
Always use `import winrm` or `from winrm import Session`.
affects: All versions
gotchaBy default, pywinrm attempts to verify SSL certificates for HTTPS connections. If connecting to Windows servers with self-signed or untrusted certificates (common in internal networks), this will lead to SSL errors.
fix
For development/testing, you can disable SSL verification by passing `verify_ssl_certs=False` to the `winrm.Session` constructor. In production, consider configuring proper certificate trust or using HTTP (port 5985) if appropriate for your security posture.
affects: All versions
gotchaOlder versions of `winrm.Session` expected separate `host` and `port` arguments. Current versions (0.4.x and above) expect a full `url` string for the WinRM endpoint.
fix
Always provide the full URL, e.g., `winrm.Session('http://<ip>:5985/wsman', ...)` instead of `winrm.Session(hostname='<ip>', port=5985, ...)`.
affects: Prior to 0.4.x
gotchaThere are subtle differences between `run_cmd` and `run_ps` when executing commands, especially regarding quoting and special characters. PowerShell commands should generally use `run_ps`.
fix
For simple executable calls (e.g., `ipconfig`), `run_cmd` is fine. For any PowerShell cmdlets or scripts, `run_ps` is recommended. Be mindful of PowerShell's quoting rules (single vs. double quotes, backticks for escaping) when constructing complex commands.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'winrm'
The 'pywinrm' library is not installed in the Python environment being used, or the environment is not activated.
fix
pip install pywinrm
pywinrm connection refused
The Windows Remote Management (WinRM) service is not running on the target Windows host, or a firewall (network or host-based) is blocking the connection to the WinRM port (default 5985 for HTTP, 5986 for HTTPS).
fix
Ensure the WinRM service is running on the Windows host by checking `services.msc` or `Get-Service WinRM` in PowerShell, and verify that network and host firewalls allow inbound connections to the WinRM port.
pywinrm authentication failed
The provided username or password is incorrect, the specified authentication method (e.g., NTLM, Basic) is not enabled or configured on the remote host, or the user lacks the necessary remote execution permissions.
fix
Verify the username and password, confirm the authentication protocol is enabled on the remote Windows machine (e.g., `winrm set winrm/config/service/auth @{Basic="true"}` for Basic auth), and ensure the user has permissions for remote operations.
pywinrm certificate verify failed
When using HTTPS (port 5986), the client failed to verify the server's SSL certificate, often due to a self-signed certificate, an untrusted Certificate Authority (CA), or a hostname mismatch in the certificate.
fix
For untrusted or self-signed certificates in non-production environments, initialize the protocol with `ssl_verify_mode='ignore'`. For production, ensure a valid, trusted certificate is installed on the server or provide the correct CA certificate chain.
Upgrade
Version history
0.5.0latest on PyPI · released Jul 16, 2024
Audit
Dependencies
requestsrequiredHTTP client for WinRM communication.
requests-ntlmrequiredNTLM authentication support for requests.
xmltodictrequiredXML parsing and serialization for WinRM messages.
gssapioptionalKerberos authentication support (Linux/macOS only).
Agent activity
14 hits · last 30 days
node
10
OpenAI (training)
1
Resources
pywinrm — pip install pywinrm · libregistry