Install & Compatibility
Where this runs
tested against v0.3.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.546s · 36.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.6s · import 0.505s · 37MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from pypsexec.client import Client
This example connects to a remote Windows host, creates a temporary service to execute a command ('whoami.exe /all'), captures its output, and then cleans up the service and connection. Credentials are pulled from environment variables.
import os
from pypsexec.client import Client
hostname = os.environ.get('PSEXEC_HOST', 'your_windows_host')
username = os.environ.get('PSEXEC_USERNAME', 'your_username')
password = os.environ.get('PSEXEC_PASSWORD', 'your_password')
if not all([hostname, username, password]):
print("Please set PSEXEC_HOST, PSEXEC_USERNAME, PSEXEC_PASSWORD environment variables.")
exit(1)
c = Client(hostname, username=username, password=password, encrypt=True)
try:
c.connect()
c.create_service()
# Run 'whoami.exe /all' command
stdout, stderr, rc = c.run_executable('whoami.exe', arguments='/all')
print(f"STDOUT:\n{stdout.decode('utf-8') if stdout else ''}")
print(f"STDERR:\n{stderr.decode('utf-8') if stderr else ''}")
print(f"Return Code: {rc}")
finally:
c.remove_service()
c.disconnect()
Debug
Known issues
breakingStarting from v0.2.0, processes are run as the native architecture's bitness (e.g., 64-bit on a 64-bit OS) by default. Previously, it always ran as a 32-bit process. Applications relying on 32-bit paths must set `wow64=True` in `run_executable()` to restore the old behavior.fixFor 32-bit process execution, add `wow64=True` to `run_executable()`: `c.run_executable('cmd.exe', arguments='/c echo Hello', wow64=True)` affects: >=0.2.0
breakingVersion 0.3.0 dropped support for Python 2.7 and 3.5. The new minimum Python version is 3.6. However, its core dependency, `smbprotocol`, now explicitly requires Python 3.9+ for full functionality.fixUpgrade your Python environment to 3.9 or newer.
affects: >=0.3.0
gotchaSMB encryption (`encrypt=True`) is only supported on Windows versions with SMB 3.x.x+ (e.g., Windows 8 / Server 2012 and newer). For older systems like Windows 7, Server 2008, or Server 2008 R2, `encrypt` must be set to `False` to avoid connection issues.fixWhen connecting to older Windows versions, initialize the client with `encrypt=False`: `c = Client('hostname', ..., encrypt=False)` affects: <0.3.0 (default behaviour affected newer versions)
gotchaWhen running commands asynchronously (`asynchronous=True`) or interactively (`interactive=True`), `pypsexec` does not return `stdout` or `stderr`. These will always be `None` in the returned tuple.fixAvoid `asynchronous=True` or `interactive=True` if you need to capture standard output or error streams.
affects: All versions
gotchaThe remote Windows host requires SMB to be running, the `ADMIN$` share to be enabled with read/write access, and the connecting user must be an administrator on the host. UAC filtering of logon tokens can prevent connections.fixEnsure the remote user has administrative privileges and ADMIN$ share access. Check UAC settings on the remote host if encountering authentication or permission errors.
affects: All versions
Errors
Common errors & fixes
Access Denied when trying to run python.exe -c "command"
The Python executable might be from the Windows Store ('WindowsApps' directory) or another location with restricted permissions, or the user's PATH environment variable is not correctly configured for remote execution.
fixEnsure `python.exe` is a standard installation and its path is accessible to the remote user. You might need to specify the full path to `python.exe` or adjust the remote system's PATH environment variable.
Cannot get stdout/stderr for long-running commands, output is None.
You are likely running the command with `asynchronous=True` or `interactive=True`, which explicitly suppresses stdout/stderr capture in `pypsexec`.
fixDo not set `asynchronous=True` or `interactive=True` if you require `stdout` and `stderr` output. For long-running tasks where output is needed, you might need a different approach (e.g., redirecting output to a file and fetching it via SMB).
GUI applications (e.g., notepad.exe) do not launch or are not visible on the remote desktop.
By default, `pypsexec` runs processes in a non-interactive session (session 0). GUI applications typically require an interactive user session to display.
fixTo launch GUI applications, you need to use `interactive=True` and potentially specify an `interactive_session` ID. This is complex as it requires an active user session and understanding of Windows session management.
PAExec binary or service remains on the remote host after execution.
In cases of critical errors or if cleanup functions are not explicitly called, the temporary PAExec service and binary might not be removed.
fixAlways wrap your `pypsexec` operations in a `try...finally` block to ensure `c.remove_service()` and `c.disconnect()` are called, even if an error occurs.
Windows Defender or other AV flags PAExec as malicious.
While `PAExec` (the underlying executable) is generally considered legitimate, some antivirus solutions might flag it due to its nature of remote execution, especially if its hash is known or if used in suspicious contexts.
fixThis is often a false positive. You may need to create an exclusion for the PAExec binary on the remote host or consider compiling your own PAExec binary from source if permitted.
Upgrade
Version history
0.3.0latest on PyPI · released Oct 21, 2021
Audit
Dependencies
smbprotocolrequiredCore dependency for SMB/RPC communication. Requires Python 3.9+ for `smbprotocol` itself.
python-gssapioptionalOptional, for Kerberos authentication on Linux systems.
pykrb5optionalOptional, for Kerberos authentication on Linux systems.