{"id":2252,"library":"pywinrm","title":"pywinrm: Python Library for Windows Remote Management","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/diyan/pywinrm","tags":["windows","remote-management","winrm","powershell","automation"],"install":[{"cmd":"pip install pywinrm","lang":"bash","label":"Base Installation"},{"cmd":"pip install pywinrm[kerberos]","lang":"bash","label":"With Kerberos support (Linux/macOS)"}],"dependencies":[{"reason":"HTTP client for WinRM communication.","package":"requests"},{"reason":"NTLM authentication support for requests.","package":"requests-ntlm"},{"reason":"XML parsing and serialization for WinRM messages.","package":"xmltodict"},{"reason":"Kerberos authentication support (Linux/macOS only).","package":"gssapi","optional":true}],"imports":[{"note":"Despite the package being `pywinrm`, the top-level module to import is `winrm`.","wrong":"from pywinrm import Session","symbol":"Session","correct":"from winrm import Session"},{"note":"Used for lower-level WinRM protocol interactions if needed.","symbol":"Protocol","correct":"from winrm import Protocol"}],"quickstart":{"code":"import winrm\nimport os\n\n# Configure target details using environment variables for security/flexibility\ntarget_host = os.environ.get('WINRM_HOST', 'localhost')\ntarget_port = os.environ.get('WINRM_PORT', '5985') # 5985 for HTTP, 5986 for HTTPS\nusername = os.environ.get('WINRM_USERNAME', 'Administrator')\npassword = os.environ.get('WINRM_PASSWORD', 'Password123!') # Use a strong password!\n\n# Establish a WinRM session\n# For HTTPS, change the URL prefix to 'https' and consider 'verify_ssl_certs=False'\n# if using self-signed certificates (use with caution in production).\nsession = winrm.Session(\n    f'http://{target_host}:{target_port}/wsman',\n    auth=(username, password)\n)\n\n# Execute a simple command\nprint(f\"Running 'hostname' on {target_host}...\")\nresult = session.run_cmd('hostname')\n\nprint(f\"Stdout: {result.std_out.decode('utf-8').strip()}\")\nprint(f\"Stderr: {result.std_err.decode('utf-8').strip()}\")\nprint(f\"Exit Code: {result.status_code}\")\n\n# Execute a PowerShell command\nprint(\"\\nRunning 'Get-Service' PowerShell command...\")\nps_result = session.run_ps('Get-Service Spooler | Select-Object Name, Status')\n\nprint(f\"Stdout: {ps_result.std_out.decode('utf-8').strip()}\")\nprint(f\"Stderr: {ps_result.std_err.decode('utf-8').strip()}\")\nprint(f\"Exit Code: {ps_result.status_code}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always use `import winrm` or `from winrm import Session`.","message":"The package installed via pip is `pywinrm`, but the module to import in your Python code is `winrm`. Forgetting this leads to `ModuleNotFoundError`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always provide the full URL, e.g., `winrm.Session('http://<ip>:5985/wsman', ...)` instead of `winrm.Session(hostname='<ip>', port=5985, ...)`.","message":"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.","severity":"gotcha","affected_versions":"Prior to 0.4.x"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}