Install & Compatibility
Where this runs
tested against v0.9.1 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WSMan
✓ from pypsrp.wsman import WSMan
✗ from pypsrp.client import WSMan
The WSMan class moved to the wsman submodule from a top-level client module in earlier versions.
RunspacePool
✓ from pypsrp.powershell import RunspacePool
✗ from pypsrp.client import RunspacePool
The RunspacePool class moved to the powershell submodule from a top-level client module in earlier versions.
PowerShell
✓ from pypsrp.powershell import PowerShell
✗ from pypsrp.client import PowerShell
The PowerShell class moved to the powershell submodule from a top-level client module in earlier versions.
This quickstart demonstrates how to connect to a remote Windows host using PowerShell Remoting (via `RunspacePool`) and execute a PowerShell command. It retrieves the status of the 'Background Intelligent Transfer Service' (BITS). Credentials are loaded from environment variables for security and portability. Remember to configure WinRM on the target host and ensure firewall rules allow the connection.
import os
from pypsrp.powershell import PowerShell, RunspacePool
# Set these environment variables for a runnable example:
# PYPSRP_HOST='your_windows_host'
# PYPSRP_USERNAME='your_username'
# PYPSRP_PASSWORD='your_password'
host = os.environ.get('PYPSRP_HOST', '')
username = os.environ.get('PYPSRP_USERNAME', '')
password = os.environ.get('PYPSRP_PASSWORD', '')
if not all([host, username, password]):
print("Please set PYPSRP_HOST, PYPSRP_USERNAME, and PYPSRP_PASSWORD environment variables to run this quickstart.")
else:
try:
# Establish a PowerShell RunspacePool connection
with RunspacePool(
server=host,
username=username,
password=password,
# For self-signed certificates or non-verified hosts, use verify_ssl=False
# connection_options={'verify_ssl': False, 'connection_timeout': 30}
) as pool:
print(f"Connected to {host} successfully.")
# Create a PowerShell pipeline
ps = PowerShell(pool)
# Add a script to execute
ps.add_script("Get-Service -Name bits | Select-Object Name, Status, DisplayName")
# Invoke the script and get the output
output = ps.invoke()
print("\n--- Command Output ---")
if output:
for item in output:
print(item)
else:
print("No output from command.")
# Check for any error or warning streams from PowerShell
if ps.streams.error:
print("\n--- PowerShell Errors ---")
for error in ps.streams.error:
print(error.message)
if ps.streams.warning:
print("\n--- PowerShell Warnings ---")
for warning in ps.streams.warning:
print(warning.message)
except Exception as e:
print(f"An error occurred: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'winrm'
The 'pypsrp' library relies on 'python-winrm' for the underlying WinRM transport, but 'python-winrm' is not always installed automatically as a direct dependency.
fixInstall the 'python-winrm' library explicitly: `pip install python-winrm`
winrm.exceptions.WinRMError: 401 Unauthorized
This error indicates that the provided credentials are incorrect, the user lacks necessary permissions, or the WinRM service on the remote server is not configured to allow the specified authentication method.
fixDouble-check the username and password, ensure the user account has permissions for WinRM, and verify the WinRM server configuration (e.g., `winrm set winrm/config/service/auth @{Basic="true"}` for Basic auth). winrm.exceptions.WinRMError: 500 WinRM transport error.
This is a generic WinRM error often indicating a problem with the WinRM service on the remote server, network connectivity issues, or an unexpected server-side error during the WinRM transport.
fixVerify that the WinRM service is running and configured correctly on the target machine, check firewall rules, ensure proper network connectivity, and review server-side WinRM logs for more specific errors.
pypsrp.exceptions.AuthenticationError
This error is raised by `pypsrp` when authentication fails, commonly due to incorrect Kerberos configuration (e.g., missing SPN, incorrect keytab, krb5.conf issues) or misconfigured CredSSP.
fixVerify Kerberos configuration (SPNs, keytabs, krb5.conf) on both client and server, or ensure CredSSP is enabled and correctly configured on both ends for the chosen authentication method.
Upgrade
Version history
0.9.1latest on PyPI · released Mar 16, 2026
Audit
Dependencies
cryptographyrequiredRequired for secure communication (encryption, hashing) within the WinRM protocol.
pemrequiredUsed for parsing PEM-encoded certificates and keys.
gssapioptionalProvides Kerberos authentication support.