pywinrm: Python Library for Windows Remote Management

Warnings

• gotcha The 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`.
• gotcha By 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.
• gotcha Older 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, ...)`.
• gotcha There 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.

Install

• pip install pywinrm Base Installation
• pip install pywinrm[kerberos] With Kerberos support (Linux/macOS)

Imports

• Session

  from winrm 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.

Quickstart

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}")