Skip to content
Fork pseudoterminals in Node.JS
Branch: master
Clone or download
Pull request Compare This branch is 1 commit behind Microsoft:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
.vscode
deps
examples
fixtures
scripts
src
typings
.editorconfig
.gitattributes
.gitignore
.npmignore
.npmrc
LICENSE
README.md
azure-pipelines.yml
binding.gyp
package.json
tsconfig.json
tslint.json

README.md

node-pty

Build Status

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+ and the winpty library in older version.

Real-world Uses

node-pty powers many different terminal emulators, including:

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.

Example Usage

var os = require('os');
var pty = require('node-pty');

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

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

ptyProcess.on('data', function(data) {
  process.stdout.write(data);
});

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

Building

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

Dependencies

Linux/Ubuntu

sudo apt install -y make python build-essential

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 Windows SDK is also needed which can be downloaded here. Only the "Desktop C++ Apps" components are needed to be installed.

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 that's accessible on the internet. We recommend launching the pty inside a container to protect your host machine.

Thread Safety

Note that node-pty is not thread safe so running it across multiple worker threads in node.js could cause issues.

Troubleshooting

Powershell gives error 8009001d

Internal Windows PowerShell error. Loading managed Windows PowerShell failed with error 8009001d.

This happens when PowerShell is launched with no SystemRoot environment variable present.

ConnectNamedPipe failed: Windows error 232

This error can occur due to anti-virus software intercepting winpty from creating a pty. To workaround this you can exclude this file from your anti-virus scanning node-pty\build\Release\winpty-agent.exe

pty.js

This project is forked from chjj/pty.js with the primary goals being to provide better support for later Node.JS versions and Windows.

License

Copyright (c) 2012-2015, Christopher Jeffrey (MIT License).
Copyright (c) 2016, Daniel Imms (MIT License).
Copyright (c) 2018, Microsoft Corporation (MIT License).

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.