microsoft/node-pty

microsoft/node-pty

Description: Fork pseudoterminals in Node.JS

Language: TypeScript

License: NOASSERTION

Stars: 1974

Forks: 318

Open issues: 42

Created: 2016-05-20T19:32:13Z

Pushed: 2026-06-26T06:47:35Z

Default branch: main

Fork: no

Archived: no

README:

node-pty


forkpty(3) bindings for node.js. This allows you to fork processes with pseudoterminal file descriptors. It returns a terminal object which allows reads and writes.

This is useful for:

• Writing a terminal emulator (eg. via xterm.js).
• Getting certain programs to *think* you're a terminal, such as when you need a program to send you control sequences.

node-pty supports Linux, macOS and Windows. Windows support is possible by utilizing the Windows conpty API on Windows 1809+.

> Note: Support for the winpty library has been removed. Windows 10 version 1809 (build 18309) or later is now required.

API

The full API for node-pty is contained within the TypeScript declaration file, use the branch/tag picker in GitHub (w) to navigate to the correct version of the API.

Example Usage

import * as os from 'node:os';
import * as pty from 'node-pty';

const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';

const ptyProcess = pty.spawn(shell, [], {
name: 'xterm-color',
cols: 80,
rows: 30,
cwd: process.env.HOME,
env: process.env
});

ptyProcess.onData((data) => {
process.stdout.write(data);
});

ptyProcess.write('ls\r');
ptyProcess.resize(100, 40);
ptyProcess.write('ls\r');

Real-world Uses

node-pty powers many different terminal emulators, including:

• Microsoft Visual Studio Code
• Hyper
• Upterm
• Script Runner for Atom.
• Theia
• FreeMAN file manager
• terminus - An Atom plugin for providing terminals inside your Atom workspace.
• x-terminal - Also an Atom plugin that provides terminals inside your Atom workspace.
• Termination - Also an Atom plugin that provides terminals inside your Atom workspace.
• atom-xterm - Also an Atom plugin that provides terminals inside your Atom workspace.
• electerm Terminal/SSH/SFTP client(Linux, macOS, Windows).
• Extraterm
• Wetty Browser based Terminal over HTTP and HTTPS
• nomad
• DockerStacks Local LAMP/LEMP stack using Docker
• TeleType: cli tool that allows you to share your terminal online conveniently. Show off mad cli-fu, help a colleague, teach, or troubleshoot.
• mesos-term: A web terminal for Apache Mesos. It allows to execute commands within containers.
• Commas: A hackable terminal and command runner.
• ENiGMA½ BBS Software: A modern BBS software with a nostalgic flair!
• Tinkerun: A new way of running Tinker.
• Tess: Hackable, simple and rapid terminal for the new era of technology 👍
• NxShell: An easy to use new terminal for Windows/Linux/MacOS platform.
• OpenSumi: A framework helps you quickly build Cloud or Desktop IDE products.
• Enjoy Git: A modern Git client featuring an intuitive user interface, built with Electron, Vue 3, and TypeScript.
• Logos: A Modern, Lightweight Code Editor, built with Electron, Vue 3, and TypeScript.

Do you use node-pty in your application as well? Please open a Pull Request to include it here. We would love to have it in our list.

Building

# Install dependencies and build C++
npm install
# Compile TypeScript -> JavaScript
npm run build

Dependencies

Node.JS 16 or Electron 19 is required to use node-pty. What version of node is supported is currently mostly bound to whatever version Visual Studio Code is using.

Linux (apt)

sudo apt install -y make python build-essential

macOS

Xcode is needed to compile the sources, this can be installed from the App Store.

Windows

npm install requires some tools to be present in the system like Python and C++ compiler. Windows users can easily install them by running the following command in PowerShell as administrator. For more information see https://github.com/felixrieseberg/windows-build-tools:

npm install --global --production windows-build-tools

The following are also needed:

• Windows SDK - only the "Desktop C++ Apps" components are needed to be installed
• Spectre-mitigated libraries - In order to avoid the build error "MSB8040: Spectre-mitigated libraries are required for this project", open the Visual Studio Installer, press the Modify button, navigate to the "Individual components" tab, search "Spectre", and install an option like "MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)" (the exact option to install will depend on your version of Visual Studio as well as your operating system architecture)

Debugging

The wiki contains instructions for debugging node-pty.

Security

All processes launched from node-pty will launch at the same permission level of the parent process. Take care particularly when using node-pty inside a server...