{"id":2251,"library":"pywinpty","title":"PyWinPTY","description":"PyWinPTY provides pseudo-terminal support for Windows, allowing Python applications to create and communicate with console processes via input and output pipes. It leverages both the native ConPTY interface and the fallback winpty library. The current version is 3.0.3, with minor releases for dependency updates and bug fixes, and a major release (3.0.0) focusing on performance and async compatibility.","status":"active","version":"3.0.3","language":"en","source_language":"en","source_url":"https://github.com/andfoy/pywinpty","tags":["windows","terminal","pty","process control","pseudo-terminal"],"install":[{"cmd":"pip install pywinpty","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"PtyProcess","correct":"from winpty import PtyProcess"},{"note":"PTY offers a lower-level interface than PtyProcess.","symbol":"PTY","correct":"from winpty import PTY"}],"quickstart":{"code":"import os\nimport time\nfrom winpty import PtyProcess\n\n# Spawn a Python interpreter in a pseudo-terminal\n# For demonstration, we use 'python', but it could be 'cmd.exe' or 'powershell.exe'\nproc = PtyProcess.spawn('python')\n\n# Write some commands to the pseudo-terminal\nproc.write('import sys\\r\\n')\nproc.write('print(\"Hello from pywinpty!\")\\r\\n')\nproc.write('print(sys.version)\\r\\n')\nproc.write('exit()\\r\\n')\n\n# Read output until the process exits\noutput = []\nwhile proc.isalive():\n    try:\n        # read() in v3.0.0+ does not accept num_bytes; reads all available.\n        chunk = proc.read().decode('utf-8', errors='ignore')\n        if chunk:\n            output.append(chunk)\n        # Give the process a moment to produce more output, prevent busy-waiting\n        time.sleep(0.01)\n    except EOFError:\n        break\n\n# Ensure all remaining output is read after process might have died but before stream closes\n# (though read() should ideally handle this)\ntry:\n    final_chunk = proc.read().decode('utf-8', errors='ignore')\n    if final_chunk:\n        output.append(final_chunk)\nexcept EOFError:\n    pass\n\nproc.close()\n\nprint(\"\\n--- Captured Output ---\")\nprint(''.join(output))\n\n# Example of sending a control character (e.g., Ctrl+C)\n# Uncomment to test, but will interrupt the spawned process\n# proc = PtyProcess.spawn('cmd.exe') # or 'python'\n# proc.sendcontrol('c') # Sends Ctrl+C\n# proc.close()","lang":"python","description":"This quickstart demonstrates how to spawn a Python interpreter within a pseudo-terminal, write commands to its input, and capture its output. It highlights the use of `PtyProcess.spawn()` and the `read()` method for interaction. The example includes error handling for `EOFError` and notes the `read()` method's behavior change in v3.0.0+."},"warnings":[{"fix":"Remove the `num_bytes` argument from calls to `proc.read()`. Implement custom buffering logic if only partial reads are desired.","message":"The `read()` method on `PtyProcess` no longer accepts a `num_bytes` parameter as of v3.0.0. It now returns all available bytes in the stream, requiring downstream consumers to handle buffering.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure you are using 64-bit Python. If installation fails, check PyPI for a compatible wheel. If building from source, install a stable or nightly Rust toolchain with `x86_64-pc-windows-msvc` target, ensure MSVC is installed (e.g., Visual Studio Build Tools), and `nuget.exe` is on your PATH if required by `maturin`. Alternatively, consider using `conda install pywinpty` or acquiring pre-built wheels from unofficial sources like Christoph Gohlke's collection for specific problematic versions (though this should be a last resort).","message":"Direct `pip install pywinpty` may fail if the appropriate wheel for your Python version and Windows architecture (e.g., 32-bit Python or a pre-release Python 3.14) is not available on PyPI, leading to an attempt to build from source. Building from source requires a Rust toolchain, MSVC, and potentially `nuget.exe` to be correctly configured and in your system PATH.","severity":"gotcha","affected_versions":"All versions, particularly on less common Python/Windows configurations or new Python versions without pre-built wheels."},{"fix":"Verify `pywinpty` is correctly installed. If issues persist, try reinstalling `pywinpty` directly via `pip install pywinpty`. Ensure your Python installation is 64-bit and compatible wheels are being used.","message":"When running Jupyter Notebooks on Windows, `pywinpty` is often a dependency. Issues with `pywinpty` installation can manifest as 'Terminals not available' errors or `ModuleNotFoundError: No module named 'winpty.cywinpty'`.","severity":"gotcha","affected_versions":"All versions, particularly when `pywinpty` is a transitive dependency."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}