{"id":2229,"library":"pypsrp","title":"PyPSRP","description":"PyPSRP is a Python library that provides client implementations for the PowerShell Remoting Protocol (PSRP) and the underlying WS-Management (WinRM) protocol. It allows Python applications to execute PowerShell commands and scripts on remote Windows machines. The current version is 0.9.1, and releases are made on an as-needed basis to add features or fix bugs.","status":"active","version":"0.9.1","language":"en","source_language":"en","source_url":"https://github.com/jborean93/pypsrp","tags":["powershell","winrm","remoting","windows","automation","protocol"],"install":[{"cmd":"pip install pypsrp","lang":"bash","label":"Standard Install"},{"cmd":"pip install pypsrp[kerberos]","lang":"bash","label":"Install with Kerberos support"}],"dependencies":[{"reason":"Required for secure communication (encryption, hashing) within the WinRM protocol.","package":"cryptography","optional":false},{"reason":"Used for parsing PEM-encoded certificates and keys.","package":"pem","optional":false},{"reason":"Provides Kerberos authentication support.","package":"gssapi","optional":true}],"imports":[{"note":"The WSMan class moved to the wsman submodule from a top-level client module in earlier versions.","wrong":"from pypsrp.client import WSMan","symbol":"WSMan","correct":"from pypsrp.wsman import WSMan"},{"note":"The RunspacePool class moved to the powershell submodule from a top-level client module in earlier versions.","wrong":"from pypsrp.client import RunspacePool","symbol":"RunspacePool","correct":"from pypsrp.powershell import RunspacePool"},{"note":"The PowerShell class moved to the powershell submodule from a top-level client module in earlier versions.","wrong":"from pypsrp.client import PowerShell","symbol":"PowerShell","correct":"from pypsrp.powershell import PowerShell"}],"quickstart":{"code":"import os\nfrom pypsrp.powershell import PowerShell, RunspacePool\n\n# Set these environment variables for a runnable example:\n# PYPSRP_HOST='your_windows_host'\n# PYPSRP_USERNAME='your_username'\n# PYPSRP_PASSWORD='your_password'\n\nhost = os.environ.get('PYPSRP_HOST', '')\nusername = os.environ.get('PYPSRP_USERNAME', '')\npassword = os.environ.get('PYPSRP_PASSWORD', '')\n\nif not all([host, username, password]):\n    print(\"Please set PYPSRP_HOST, PYPSRP_USERNAME, and PYPSRP_PASSWORD environment variables to run this quickstart.\")\nelse:\n    try:\n        # Establish a PowerShell RunspacePool connection\n        with RunspacePool(\n            server=host,\n            username=username,\n            password=password,\n            # For self-signed certificates or non-verified hosts, use verify_ssl=False\n            # connection_options={'verify_ssl': False, 'connection_timeout': 30}\n        ) as pool:\n            print(f\"Connected to {host} successfully.\")\n            # Create a PowerShell pipeline\n            ps = PowerShell(pool)\n            \n            # Add a script to execute\n            ps.add_script(\"Get-Service -Name bits | Select-Object Name, Status, DisplayName\")\n            \n            # Invoke the script and get the output\n            output = ps.invoke()\n            \n            print(\"\\n--- Command Output ---\")\n            if output:\n                for item in output:\n                    print(item)\n            else:\n                print(\"No output from command.\")\n\n            # Check for any error or warning streams from PowerShell\n            if ps.streams.error:\n                print(\"\\n--- PowerShell Errors ---\")\n                for error in ps.streams.error:\n                    print(error.message)\n            if ps.streams.warning:\n                print(\"\\n--- PowerShell Warnings ---\")\n                for warning in ps.streams.warning:\n                    print(warning.message)\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later.","message":"PyPSRP requires Python 3.10 or newer. Attempting to install or run on older Python versions will result in dependency resolution failures or runtime errors.","severity":"breaking","affected_versions":"<0.9.0"},{"fix":"Ensure WinRM is enabled and configured correctly on the remote server. Verify network connectivity and firewall rules.","message":"WinRM and PowerShell Remoting require specific configurations on the target Windows host, including enabling WinRM (e.g., `winrm quickconfig` in an elevated PowerShell) and ensuring firewall rules allow traffic on ports 5985 (HTTP) or 5986 (HTTPS).","severity":"gotcha","affected_versions":"All"},{"fix":"Always check `PowerShell.streams.error` and `PowerShell.streams.warning` after invoking a command to detect and handle remote errors gracefully.","message":"Remote PowerShell command errors (e.g., cmdlets failing) are not raised as Python exceptions by default. Instead, they are captured in the `ps.streams.error` or `ps.streams.warning` lists.","severity":"gotcha","affected_versions":"All"},{"fix":"For Kerberos, install `pypsrp[kerberos]` and ensure your system's Kerberos client is configured. For SSL issues, consider setting `verify_ssl=False` in `connection_options` for testing (not recommended for production) or ensure a valid certificate chain.","message":"Authentication can be complex. NTLM and Kerberos are supported, but Kerberos requires the `gssapi` dependency and proper Kerberos configuration (e.g., `krb5.conf`). SSL/TLS certificate verification can also be an issue, especially with self-signed certificates.","severity":"gotcha","affected_versions":"All"},{"fix":"For executing PowerShell scripts and cmdlets, always use `RunspacePool` and `PowerShell`. Use `WSMan` only if you need to interact with raw WinRM for non-PowerShell purposes (e.g., CIM operations).","message":"PyPSRP provides both low-level WS-Management (WinRM) through `WSMan` and higher-level PowerShell Remoting through `RunspacePool` and `PowerShell`. Using `WSMan` directly for PowerShell commands will be significantly more complex as it doesn't handle the PowerShell serialization and object model.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}