Introduction

Installation

Install nut.js and configure your environment for desktop automation.

Requirements

Node.js 22.x or later
npm, yarn, or pnpm
Windows 10+, macOS 14+, or Linux with X11

Package Installation

Install the core nut.js package using your preferred package manager:

npm install @nut-tree/nut-js

Prebuilt Packages

nut.js comes with prebuilt native binaries for all supported platforms. This means you don't need any build tools or compilers installed—just install and start coding.

Info

The prebuilt packages are available through a paid subscription that supports ongoing development. Visit the pricing page for more information.

Platform-Specific Setup

macOS

On macOS, you need to grant accessibility permissions to your terminal or Node.js application:

Open System Preferences → Security & Privacy → Privacy
Select "Accessibility" from the left sidebar
Click the lock icon to make changes
Add your terminal application (Terminal, iTerm2, VS Code, etc.)

Warning

Without accessibility permissions, nut.js will not be able to control the mouse or keyboard on macOS.

Linux

On Linux, ensure you have X11 installed. Most desktop distributions include this by default. For headless servers, you may need to install a virtual display.

Tip

For CI/CD environments, consider using Xvfb (X Virtual Framebuffer) to create a virtual display.

Windows

No additional setup is required on Windows. nut.js works out of the box.

Verify Installation

Create a test script to verify everything is working:

test.ts

import { mouse } from "@nut-tree/nut-js";

const position = await mouse.getPosition();
console.log(`Mouse position: ${position.x}, ${position.y}`);

Run the script with npx tsx test.ts. If you see the mouse coordinates printed, you're all set!