ptyprocess

0.7.0 verified Tue May 12 auth: no python install: stale quickstart: stale

A library to run subprocesses in a pseudo terminal, version 0.7.0. It is actively maintained with a release cadence focused on improvements and CI updates.

pip install ptyprocess

Common errors

error ModuleNotFoundError: No module named 'ptyprocess' ↓

cause The 'ptyprocess' library is not installed in the current Python environment or the Python interpreter being used cannot find it.

fix

Install the library using pip: pip install ptyprocess or python -m pip install ptyprocess. If using a virtual environment, ensure it's activated before installation.

error OSError: out of pty devices ↓

cause The operating system has reached its limit for the number of available pseudo-terminal (pty) devices.

fix

This is a system-level issue. You might need to close other terminal sessions, reboot the system, or increase the system's kernel.pty.max limit (e.g., by modifying /etc/sysctl.conf and applying with sysctl -p).

error ptyprocess.PtyProcessError: Could not terminate the child. ↓

cause This error occurs when `ptyprocess` fails to terminate the child process it spawned, often because the child process is no longer running or `waitpid()` was called by another part of the program.

fix

Ensure that ptyprocess.PtyProcess.close() is called correctly and that no other part of the code or other processes are managing the child process's lifecycle (e.g., calling os.waitpid) concurrently. When using pexpect (which uses ptyprocess), handle termination gracefully, possibly by checking isalive() before attempting to close if the child process might exit independently.

error Failed to open PTY: Permission denied ↓

cause The user or process running the application does not have the necessary permissions to create or open pseudo-terminal devices, often related to the `/dev/pts` file system.

fix

Check and adjust file permissions for /dev/pts/ptmx (e.g., sudo chmod 666 /dev/pts/ptmx). Ensure that devpts is correctly mounted.

Warnings

gotcha Not all subprocesses behave the same in a pseudo terminal. ↓

fix Test subprocess compatibility before production use.

deprecated Older methods of invoking processes may not fully utilize the pty. ↓

fix Update your method calls to the new standardized approach.

breaking The `PTYProcess` class has been moved or removed from the top-level `ptyprocess` package, resulting in an ImportError. ↓

fix Update your import statement from `from ptyprocess import PTYProcess` to `from ptyprocess.ptyprocess import PTYProcess`, or consult the library's documentation for the correct import path for your version.

breaking The main class 'PTYProcess' has been renamed to 'PtyProcess'. Attempting to import 'PTYProcess' will result in an ImportError. ↓

fix Update your code to import 'PtyProcess' instead of 'PTYProcess'.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - - -

3.11 slim (glibc) - - - -

3.12 alpine (musl) - - - -

3.12 slim (glibc) - - - -

3.13 alpine (musl) - - - -

3.13 slim (glibc) - - - -

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

PTYProcess
```
from ptyprocess import PTYProcess
```
Common mistake is to use 'import ptyprocess' instead, which doesn't expose the PTYProcess class directly.

Quickstart stale last tested: 2026-04-23

This quickstart launches a subprocess to list files in the current directory.

import os
from ptyprocess import PTYProcess

proc = PTYProcess.spawn(['ls', '-l'])
print(proc.read())