ZetCode

Python pexpect

last modified November 17, 2026 Python 3.15

In this article we show how to control interactive programs in Python with the pexpect module.

Pexpect is a pure Python module for spawning child applications, controlling them, and responding to expected patterns in their output. It is modelled on the Tcl Expect tool. Pexpect is used to automate programs that ask questions on the terminal, such as ssh, passwd, ftp, installers, or interactive shells and REPLs, and to test such programs.

Unlike the subprocess module, which talks to a child process through pipes, pexpect runs the child in a pseudo-terminal (pty). The child program believes it talks to a real user at a terminal. This matters because many programs behave differently when their output is not a terminal: they buffer their output, or, as ssh and sudo do, read passwords directly from the terminal instead of the standard input.

There are two basic functions: run and spawn. The run function executes a command and returns its output; it is useful for simple interactions. The spawn class is more powerful: it starts a child program and lets us interact with it by sending lines and expecting responses. Pexpect works on Linux, macOS, and other Unix-like systems; on Windows, only the limited popen_spawn interface without a terminal is available.

The examples were tested with Python 3.15 and pexpect 4.9 on Linux.

$ pip install pexpect

The run function

The run function runs the given command, waits for it to finish, and returns all its output. The standard error output is included, since both streams go to the same terminal.

run_echo.py
import pexpect

out = pexpect.run('echo hello')
print(out)

out = pexpect.run('echo hello', encoding='utf-8')
print(repr(out))

In the program, we run the echo command.

out = pexpect.run('echo hello')

By default, the output is returned as bytes. Note the \r\n line ending: the terminal translates each newline into a carriage return and a newline, just as when a program writes to a real terminal.

out = pexpect.run('echo hello', encoding='utf-8')

With the encoding parameter, pexpect decodes the output and returns a string. The spawn class accepts the same parameter.

$ python run_echo.py
b'hello\r\n'
'hello\r\n'

Exit status

With withexitstatus=True, the run function returns a tuple of the output and the exit status of the command.

run_status.py
import pexpect

out, status = pexpect.run('ls /etc/hostname /nonexistent',
                          withexitstatus=True, encoding='utf-8')

print(f'exit status: {status}')
print(out, end='')

The ls command lists one existing and one missing file. It prints the error message, lists the existing file, and ends with status 2. The command is found by searching the PATH, so the error message contains its full path.

$ python run_status.py
exit status: 2
/usr/bin/ls: cannot access '/nonexistent': No such file or directory
/etc/hostname

Answering prompts with run

The events parameter of run is a dictionary that maps patterns to responses. Whenever a pattern appears in the output, the corresponding string is sent to the program.

ask.py
name = input('Enter your name: ')
city = input('Enter your city: ')

print(f'Hello {name} from {city}!')

The ask.py program asks for a name and a city. We use it in several examples.

run_events.py
import pexpect

events = {
    'name: ': 'Peter\n',
    'city: ': 'Bratislava\n',
}

out = pexpect.run('python ask.py', events=events, encoding='utf-8')
print(out, end='')

The program answers both questions. The keys are regular expressions; the values are sent as they are, so they must end with a newline, which works as pressing Enter.

$ python run_events.py
Enter your name: Peter
Enter your city: Bratislava
Hello Peter from Bratislava!

The spawn class

The spawn class executes a child program and allows us to interact with it. The expect method reads the output of the child until a pattern is matched. The pattern can be a string, which is compiled to a regular expression, a compiled regular expression, the pexpect.EOF or pexpect.TIMEOUT constants, or a list of any of those.

spawn_eof.py
import pexpect

child = pexpect.spawn('uname -sr', encoding='utf-8')
child.expect(pexpect.EOF)

print(f'kernel: {child.before.strip()}')

child.close()
print(f'exit status: {child.exitstatus}')

In the program, we run the uname command and read all its output.

child.expect(pexpect.EOF)

With pexpect.EOF, we wait until the child closes its output, which usually means that it has exited.

print(f'kernel: {child.before.strip()}')

After each call to expect, the before attribute contains the text read before the match and the after attribute the matched text.

child.close()
print(f'exit status: {child.exitstatus}')

The close method closes the connection to the child; after that, the exitstatus attribute contains its exit status.

$ python spawn_eof.py
kernel: Linux 6.8.0-149-generic
exit status: 0

Shell features

Neither run nor spawn use a shell. The command string is split into a program name and arguments, so pipes, redirections, wildcards, and variables do not work. If we need them, we must run a shell explicitly.

shell_cmd.py
import pexpect

out = pexpect.run('echo *.py | wc -w', encoding='utf-8')
print(repr(out))

out = pexpect.run('bash -c "echo *.py | wc -w"', encoding='utf-8')
print(repr(out))

child = pexpect.spawn('bash', ['-c', 'ls /usr | wc -l'], encoding='utf-8')
child.expect(pexpect.EOF)
print(repr(child.before))

The first command passes *.py, |, wc, and -w as arguments to echo, which prints them. In the second and third commands, bash -c interprets the command line. The spawn class also accepts the arguments as a list, which avoids problems with quoting.

$ python shell_cmd.py
'*.py | wc -w\r\n'
'19\r\n'
'15\r\n'

Sending input

The sendline method sends a string followed by a newline to the child; the send method sends the string only. A typical interaction alternates expect and sendline calls.

dialog.py
import pexpect

child = pexpect.spawn('python ask.py', encoding='utf-8')

child.expect('name: ')
child.sendline('Lucia')

child.expect('city: ')
child.sendline('Kosice')

child.expect(r'Hello (\w+) from (\w+)!')
print(child.after)
print(child.match.groups())

child.expect(pexpect.EOF)
child.close()
print(f'exit status: {child.exitstatus}')

We answer the questions of the ask.py program and parse its final message.

child.expect('name: ')
child.sendline('Lucia')

We wait for the prompt before we send the answer. Sending input before the program asks for it often works, but waiting for the prompt makes the interaction reliable.

child.expect(r'Hello (\w+) from (\w+)!')
print(child.after)
print(child.match.groups())

The match attribute holds the regular expression match object, so we can read the captured groups.

$ python dialog.py
Hello Lucia from Kosice!
('Lucia', 'Kosice')
exit status: 0

Logging the session

The logfile attribute receives everything that is sent to and read from the child. The logfile_read and logfile_send attributes receive only one direction. Setting a log file to sys.stdout is a handy way to watch the session.

logfile.py
import sys

import pexpect

child = pexpect.spawn('python ask.py', encoding='utf-8')
child.logfile_read = sys.stdout

child.expect('name: ')
child.sendline('Lucia')

child.expect('city: ')
child.sendline('Kosice')

child.expect(pexpect.EOF)

We log everything read from the child. Since the terminal echoes what we type, the log contains our answers as well; it looks the same as if we ran the program ourselves. With encoding set, the log file must be a text file; without it, a binary file is needed, for instance open('session.log', 'wb').

$ python logfile.py
Enter your name: Lucia
Enter your city: Kosice
Hello Lucia from Kosice!

Expecting multiple patterns

When we pass a list of patterns to expect, it returns the index of the pattern that matched first. This allows us to react to different outcomes. In the next example, we play a number guessing game.

guess.py
import sys

secret = int(sys.argv[1])
tries = 0

while True:
    guess = int(input('Your guess (1-1000): '))
    tries += 1

    if guess < secret:
        print('Too low')
    elif guess > secret:
        print('Too high')
    else:
        print(f'Correct! You needed {tries} tries.')
        break

The guess.py program asks for a number between 1 and 1000 and tells us whether the guess is too low or too high. The secret number is given on the command line.

solver.py
import pexpect

child = pexpect.spawn('python guess.py 627', encoding='utf-8')

low, high = 1, 1000

while True:
    child.expect(r'\(1-1000\): ')
    guess = (low + high) // 2
    child.sendline(str(guess))

    i = child.expect(['Too low', 'Too high', r'Correct! You needed (\d+) tries'])

    if i == 0:
        print(f'{guess} is too low')
        low = guess + 1
    elif i == 1:
        print(f'{guess} is too high')
        high = guess - 1
    else:
        print(f'found {guess} in {child.match.group(1)} tries')
        break

child.expect(pexpect.EOF)

The solver uses binary search, so it needs at most ten guesses.

child.expect(r'\(1-1000\): ')

The pattern is a regular expression, so the parentheses must be escaped.

i = child.expect(['Too low', 'Too high', r'Correct! You needed (\d+) tries'])

Depending on the answer, we move the lower or the upper bound of the search interval. When the number is found, we read the number of tries from the captured group.

$ python solver.py
500 is too low
750 is too high
625 is too low
687 is too high
656 is too high
640 is too high
632 is too high
628 is too high
626 is too low
found 627 in 10 tries

Timeouts

By default, expect waits 30 seconds for a pattern. If the pattern does not appear, it raises the pexpect.TIMEOUT exception; if the child exits before, it raises pexpect.EOF. When we include the pexpect.TIMEOUT and pexpect.EOF constants in the list of patterns, expect returns their indexes instead of raising exceptions.

login.py
import time

user = input('Username: ')
password = input('Password: ')

time.sleep(0.5)

if user == 'admin' and password == 's3cret':
    print('Welcome, admin')
    input('> ')
elif user == 'admin':
    print('Access denied')
else:
    time.sleep(5)

The login.py program simulates a login. It welcomes the administrator, refuses a wrong password, and hangs for an unknown user.

outcomes.py
import pexpect

attempts = [('admin', 's3cret'), ('admin', 'oops'), ('guest', 'guest')]

for user, password in attempts:
    child = pexpect.spawn('python login.py', encoding='utf-8', timeout=2)
    child.expect('Username: ')
    child.sendline(user)
    child.expect('Password: ')
    child.sendline(password)

    i = child.expect(['Welcome', 'Access denied', pexpect.EOF, pexpect.TIMEOUT])

    match i:
        case 0:
            print(f'{user}/{password}: logged in')
        case 1:
            print(f'{user}/{password}: wrong password')
        case 2:
            print(f'{user}/{password}: program ended')
        case 3:
            print(f'{user}/{password}: no answer in {child.timeout} s')

    child.close(force=True)

We try three logins and handle all possible outcomes with a match statement.

child = pexpect.spawn('python login.py', encoding='utf-8', timeout=2)

The timeout parameter sets the default timeout in seconds for all expect calls of the child.

child.close(force=True)

The force=True option kills the child if it does not exit after it receives the SIGHUP and SIGINT signals.

$ python outcomes.py
admin/s3cret: logged in
admin/oops: wrong password
guest/guest: no answer in 2 s

The TIMEOUT exception

The timeout parameter of expect overrides the default for one call. Without pexpect.TIMEOUT in the patterns, the method raises an exception.

timeout_exc.py
import pexpect

child = pexpect.spawn('python login.py', encoding='utf-8')
child.expect('Username: ')
child.sendline('guest')
child.expect('Password: ')
child.sendline('guest')

try:
    child.expect('Welcome', timeout=2)
except pexpect.TIMEOUT:
    print('timeout: the program did not answer in two seconds')
    print(f'is alive: {child.isalive()}')
    print(f'buffer: {child.before!r}')
finally:
    child.close(force=True)

We catch the exception. The child is still running, and the before attribute contains what was read so far: only the echo of our input.

$ python timeout_exc.py
timeout: the program did not answer in two seconds
is alive: True
buffer: 'guest\r\n'

The replwrap module

The replwrap module simplifies working with interactive interpreters, such as Python or bash. The run_command method sends a command, waits for the next prompt, and returns the output.

replwrap_py.py
import os

from pexpect import replwrap

os.environ['PYTHON_BASIC_REPL'] = '1'
py = replwrap.python('python -q')

print(py.run_command('import math'), end='')
print(py.run_command('math.factorial(20)'), end='')
print(py.run_command('[x * x for x in range(6)]'), end='')
print(py.run_command('1 / 0').splitlines()[-1])

We start a Python interpreter and evaluate a few expressions.

os.environ['PYTHON_BASIC_REPL'] = '1'
py = replwrap.python('python -q')

Since Python 3.13, the interactive interpreter colours its prompts and output and redraws the input line, which produces many escape sequences. The PYTHON_BASIC_REPL environment variable selects the basic REPL. The -q option suppresses the version banner.

print(py.run_command('1 / 0').splitlines()[-1])

Errors are returned as ordinary output; we print the last line of the traceback.

$ python replwrap_py.py
2432902008176640000
[0, 1, 4, 9, 16, 25]
ZeroDivisionError: division by zero

Wrapping bash

The replwrap.bash function starts bash with a special prompt that is unlikely to appear in the output. The shell keeps its state between commands, so the cd command affects the following ones.

replwrap_bash.py
from pexpect import replwrap

bash = replwrap.bash()

bash.run_command('cd /usr')
print(bash.run_command('pwd'), end='')
print(bash.run_command('ls -d *bin'), end='')
print(bash.run_command('echo $((6 * 7))'), end='')

We change the directory, list the directories with names ending in bin, and compute an arithmetic expression.

$ python replwrap_bash.py
/usr
bin  sbin
42

Interacting with the user

The interact method gives the control of the child to the user. The keystrokes are sent to the child and its output is printed on the screen. This is useful when a script automates the tedious part of a session, such as logging in, and then lets the user continue.

interact.py
import pexpect

child = pexpect.spawn('python -q', encoding='utf-8')
child.expect('>>> ')
child.sendline('import math')
child.expect('>>> ')

print('math is imported; the REPL is yours, press Ctrl+D to quit')
child.interact()

The script starts a Python REPL, imports the math module, and hands the session over to the user. The method returns when the child exits or when the user presses the escape character, Ctrl+], by default.

SSH test server

The ssh client reads passwords directly from the terminal, so it cannot be fed through a pipe. This makes it a classic task for pexpect. For the SSH examples, we run an OpenSSH server in a Docker container with a user7 account and the s3cret password.

Dockerfile
FROM debian:trixie-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends openssh-server busybox \
    && rm -rf /var/lib/apt/lists/* \
    && mkdir -p /run/sshd \
    && useradd --create-home --shell /bin/bash user7 \
    && echo 'user7:s3cret' | chpasswd

EXPOSE 22
CMD ["/usr/sbin/sshd", "-D", "-e"]

We build the image and start a container with port 22 published on port 2222 of the local machine. The 127.0.0.1 prefix makes the port reachable only from this computer.

$ docker build -q -t ssh-test .
sha256:76f1361905b4fc5ab76ffdb58824f86893d418d88e40f6cbd98d1920a48eb80c
$ docker run -d --name ssh-test -p 127.0.0.1:2222:22 ssh-test
3f9f9dbdfac8c9d7228c73c90151e0448f657ca95d7f3474b1c4d71d114ca21d
$ docker ps --format '{{.Names}} {{.Status}} {{.Ports}}'
ssh-test Up 1 second 127.0.0.1:2222->22/tcp

Logging in with ssh

The first connection to a server asks us to confirm its host key; the following ones ask only for the password. A robust script expects all the prompts in a loop.

ssh_login.py
import os

import pexpect

env = os.environ | {'TERM': 'dumb'}
child = pexpect.spawn('ssh -p 2222 user7@localhost', env=env,
                      encoding='utf-8', timeout=10)

while True:
    i = child.expect([r'continue connecting \(yes/no.*\)\? ', 'password: ',
                      r'\$ ', 'Permission denied'])
    if i == 0:
        print('new host key, accepting')
        child.sendline('yes')
    elif i == 1:
        print('sending password')
        child.sendline('s3cret')
    elif i == 2:
        print('logged in')
        break
    else:
        print('permission denied')
        child.close(force=True)
        raise SystemExit(1)

child.sendline('uname -s -m')
child.expect(r'\$ ')
print(child.before.splitlines()[1])

child.sendline('exit')
child.expect(pexpect.EOF)
child.close()
print(f'exit status: {child.exitstatus}')

The script logs in to the server, runs the uname command, and logs out.

env = os.environ | {'TERM': 'dumb'}
child = pexpect.spawn('ssh -p 2222 user7@localhost', env=env,
                      encoding='utf-8', timeout=10)

The remote shell gets the terminal type from the client. With a regular terminal type, bash enables the bracketed paste mode and sends escape sequences such as \x1b[?2004h around each prompt. The dumb terminal type keeps the output clean.

i = child.expect([r'continue connecting \(yes/no.*\)\? ', 'password: ',
                  r'\$ ', 'Permission denied'])

We expect four situations: the host key question, the password prompt, the shell prompt, and a refused login. The loop ends when we see the shell prompt.

child.sendline('uname -s -m')
child.expect(r'\$ ')
print(child.before.splitlines()[1])

The text before the next prompt starts with the echo of our command; the second line is its output.

We run the script twice. The second time, the host key is already stored in ~/.ssh/known_hosts, so we are asked only for the password. Accepting an unknown host key blindly is fine for a test container; on a real network, compare the fingerprint first.

$ python ssh_login.py
new host key, accepting
sending password
logged in
Linux x86_64
exit status: 0
$ python ssh_login.py
sending password
logged in
Linux x86_64
exit status: 0

The pxssh module

The pxssh module extends spawn with SSH-specific methods. The login method handles the host key question and the password and replaces the shell prompt with a unique string, so that the prompt method can reliably detect the end of a command's output.

ssh_pxssh.py
import os

from pexpect import pxssh

env = os.environ | {'TERM': 'dumb'}
ssh = pxssh.pxssh(env=env, encoding='utf-8')

try:
    ssh.login('localhost', 'user7', 's3cret', port=2222)
except pxssh.ExceptionPxssh as e:
    raise SystemExit(f'login failed: {e}')

for cmd in ('whoami', 'pwd', 'grep PRETTY /etc/os-release', 'ls /nonexistent'):
    ssh.sendline(cmd)
    ssh.prompt()
    output = ssh.before.splitlines()[1:]

    ssh.sendline('echo $?')
    ssh.prompt()
    status = ssh.before.splitlines()[1]

    print(f'{cmd} [{status}]')
    for line in output:
        print(f'  {line}')

ssh.logout()

We run several commands on the server and print their output and exit status.

ssh.login('localhost', 'user7', 's3cret', port=2222)

The login method raises pxssh.ExceptionPxssh if the login fails.

ssh.sendline(cmd)
ssh.prompt()
output = ssh.before.splitlines()[1:]

The prompt method waits for the shell prompt. We skip the first line, which is the echoed command.

ssh.sendline('echo $?')
ssh.prompt()
status = ssh.before.splitlines()[1]

A shell session does not report exit statuses of individual commands. We print the $? variable, which holds the status of the last command.

$ python ssh_pxssh.py
whoami [0]
  user7
pwd [0]
  /home/user7
grep PRETTY /etc/os-release [0]
  PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
ls /nonexistent [2]
  ls: cannot access '/nonexistent': No such file or directory

Failed login

With a wrong password, the login method raises an exception.

ssh_bad.py
import os

from pexpect import pxssh

env = os.environ | {'TERM': 'dumb'}
ssh = pxssh.pxssh(env=env, encoding='utf-8')

try:
    ssh.login('localhost', 'user7', 'wrong', port=2222)
except pxssh.ExceptionPxssh as e:
    print(f'login failed: {e}')

We catch the exception and print its message.

$ python ssh_bad.py
login failed: password refused

Source

Pexpect documentation

pxssh – control an SSH session

In this article we have automated interactive programs with the Python pexpect module. See also Python subprocess, Python execute command, and Python Paramiko.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Python tutorials.