Awesome Open Source
Awesome Open Source


A fully functional terminal in your browser.


How does this work?

On the backend:

  • A Flask server is running
  • The Flask server uses flask-socketio, a websocket library for Flask and socketio
  • A pty ("pseudo-terminal") is spawned that runs bash.
    • You can think of a pty as a way to serialize/deserialize a terminal session. The Python docs describe it as "starting another process and being able to write to and read from its controlling terminal programmatically".

On the frontend:

  • Xterm.js is used to render Xterm output data in the browser.
    • This means escape codes used by terminals to control the cursor location, color, and other options can be passed directly to Xterm.js and Xterm.js will faithfully render them as a terminal would.
    • Output from the pty process on the backend is fed into it.
    • Input from the browser is passed via websocket to the pty's input


The real purpose of this is to show a basic proof of concept on how to bring Xterm.js, Python, Flask, and Websockets together to run a pty in the browser.

This is a

  • starting point to build your own web app with a terminal
  • learning tool to understand what a pty is, and how to use one in Python
  • way to see Flask and Flask-SocketIO in action
  • way to play around with Xterm.js in a meaningful environment


There are a few ways to install and run.

Clone & Run Locally

Clone this repository, enter the pyxtermjs directory, then run:

> python -m venv venv  # must be python3.6+
> venv/bin/pip install -r requirements.txt
> venv/bin/python -m pyxtermjs
serving on

Install or Run latest version on PyPI

You can use pipx to try it out.

> pipx run pyxtermjs
serving on

You can also and have pyxtermjs installed in an isolated environment, yet available on your $PATH with

> pipx install pyxtermjs

Run from GitHub source

Use pipx for this as well.

> pipx run --spec git+ pyxtermjs
serving on


> pyxtermjs --help
usage: pyxtermjs [-h] [-p PORT] [--host HOST] [--debug] [--version]
                 [--command COMMAND] [--cmd-args CMD_ARGS]

A fully functional terminal in your browser.

optional arguments:
  -h, --help            show this help message and exit
  -p PORT, --port PORT  port to run server on (default: 5000)
  --host HOST           host to run server on (use to allow access
                        from other hosts) (default:
  --debug               debug the server (default: False)
  --version             print version and exit (default: False)
  --command COMMAND     Command to run in the terminal (default: bash)
  --cmd-args CMD_ARGS   arguments to pass to command (i.e. --cmd-args='arg1
                        arg2 --flag') (default: )

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (55,471
terminal (750
flask (540
terminal-emulators (40
flask-application (36