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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
List all Python tutorials.