Use screenshot-desktop when you need a screenshot of the computer running your Node.js process. Install it with npm, call the Promise-based function, and either receive image bytes in a Buffer or provide filename to save the image directly. The default output is JPG; set format: 'png' for PNG. On multi-monitor systems, call listDisplays() and pass a display ID with screen, or call all() for one image per monitor.
This guide covers installation, complete scripts, display selection, file handling, Linux requirements, failure diagnosis, and the point at which a hosted screenshot API is a better fit.
What screenshot-desktop captures
screenshot-desktop captures the local machine’s display, not a remote web page. Your Node.js program must run on the computer whose screen you want to record, and that computer must have an active desktop session visible to the capture backend. The package returns Promises, so it fits naturally into asynchronous Node.js code.
The npm listing identified version 1.15.6 at the time of the supplied documentation; check npm before pinning a production dependency because releases can change. The project is MIT-licensed. Install it in an existing project with:
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
npm install --save screenshot-desktopOn macOS and Windows, the project documentation says no additional dependency is required. Linux requires ImageMagick according to the README. Linux users can select the backend with the linuxLibrary option, whose documented values are imagemagick and scrot.
Capture a screenshot in Node.js
Receive the default JPG as a Buffer
A call with no options resolves to a Buffer containing JPG data:
const screenshot = require('screenshot-desktop')
screenshot()
.then((img) => {
console.log(`Captured ${img.length} bytes`)
// img is a Buffer containing JPG data by default
})
.catch((err) => {
console.error('Screenshot failed:', err)
})Because the result is a Buffer, you can send it to an HTTP response, upload it to object storage, or write it yourself. The Promise rejects when the underlying capture command fails, so always attach a catch handler or use try/catch with await.
Use async/await
This complete script captures the screen and writes the bytes to a file using Node’s built-in filesystem module:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →const screenshot = require('screenshot-desktop')
const fs = require('node:fs/promises')
async function main() {
try {
const image = await screenshot()
await fs.writeFile('screen.jpg', image)
console.log('Wrote screen.jpg')
} catch (error) {
console.error(error)
process.exitCode = 1
}
}
main()Run it with node capture.js. The extension should match the actual format: the default is JPG, so use .jpg unless you explicitly request PNG.
Choose PNG or JPG output
The documented format values are jpg and png. JPG is the default. PNG is lossless and often preferable for text-heavy interfaces, diagrams, or pixel-level comparisons; JPG generally produces smaller files for photographic content.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
const screenshot = require('screenshot-desktop')
const fs = require('node:fs/promises')
async function main() {
const png = await screenshot({ format: 'png' })
await fs.writeFile('screen.png', png)
}
main().catch((error) => {
console.error(error)
process.exitCode = 1
})Do not pass arbitrary format names. The package documentation only guarantees png and jpg; conversion to WebP, TIFF, or another format requires a separate image-processing step that is outside this package’s documented API.
Save directly with filename
Set filename when you want the package to write the image instead of returning image bytes for you to persist. Relative and absolute paths are documented:
const screenshot = require('screenshot-desktop')
screenshot({ filename: 'shots/demo.jpg' })
.then((savedPath) => {
console.log('Saved at:', savedPath)
})
.catch(console.error)The Promise resolves to the absolute output path. Ensure the parent directory already exists; create it first when your script targets a generated path:
const screenshot = require('screenshot-desktop')
const fs = require('node:fs/promises')
async function main() {
await fs.mkdir('shots', { recursive: true })
const path = await screenshot({
filename: 'shots/dashboard.png',
format: 'png'
})
console.log(path)
}
main().catch((error) => {
console.error(error)
process.exitCode = 1
})Use an absolute path when a service, scheduler, or systemd unit may start with an unexpected working directory. Also check write permissions for the account running Node.js.
Select a monitor or capture every display
Discover display IDs
listDisplays() resolves to objects containing id and name. Print them before choosing a target:
const screenshot = require('screenshot-desktop')
screenshot.listDisplays()
.then((displays) => {
console.table(displays)
})
.catch(console.error)Capture one selected display
Pass one of those IDs through the screen option. This example chooses the last display returned by the operating system and saves a PNG:
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
const screenshot = require('screenshot-desktop')
async function main() {
const displays = await screenshot.listDisplays()
if (displays.length === 0) {
throw new Error('No displays were reported')
}
const selected = displays[displays.length - 1]
const path = await screenshot({
screen: selected.id,
format: 'png',
filename: `display-${selected.id}.png`
})
console.log(`Captured ${selected.name}: ${path}`)
}
main().catch((error) => {
console.error(error)
process.exitCode = 1
})Persist the ID only if your environment keeps stable IDs. Some operating systems or docking arrangements can enumerate displays differently after hardware changes, so a robust workflow lists displays and validates the chosen ID at runtime.
Capture every connected display
Use the convenience helper all() when you need one Buffer per screen:
const screenshot = require('screenshot-desktop')
const fs = require('node:fs/promises')
async function main() {
const images = await screenshot.all()
await Promise.all(
images.map((image, index) => fs.writeFile(`display-${index + 1}.jpg`, image))
)
console.log(`Wrote ${images.length} files`)
}
main().catch((error) => {
console.error(error)
process.exitCode = 1
})all() returns an array of Buffers. If you need PNG files, verify that the helper’s supported behavior matches your installed version; the documented helper example returns image Buffers without documenting an additional format argument.
Linux backend requirements
Install ImageMagick on Linux before running the package. The README also documents linuxLibrary: 'imagemagick' and linuxLibrary: 'scrot'. Choose ImageMagick when you need the documented format or monitor controls: the README states that scrot does not support format selection or screen selection.
const screenshot = require('screenshot-desktop')
screenshot({
linuxLibrary: 'imagemagick',
format: 'png',
filename: '/tmp/linux-screen.png'
})
.then(console.log)
.catch(console.error)A headless Linux server, SSH session without a graphical display, container, or locked desktop may not provide a capturable screen even when ImageMagick is installed. This package is for the local graphical session; it is not a browser renderer or a virtual-display manager.
What the documented API does not provide
The cited documentation guarantees filename, format, and Linux-only linuxLibrary, plus listDisplays() and all(). It does not document selecting a window or rectangular region, annotations, OCR, video recording, browser automation, or HTML rendering. If you need those capabilities, add a separately documented tool rather than assuming screenshot-desktop supports them.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
Troubleshooting checklist
“Cannot find module ‘screenshot-desktop’”
Install the dependency in the project from which you run Node, then confirm that node_modules/screenshot-desktop exists. Running a script from another directory or using a different Node installation can make a successful install appear missing.
Linux reports a missing command or no image
Install ImageMagick and retry with linuxLibrary: 'imagemagick'. If you selected scrot, remove that setting when you need PNG or monitor selection because the documented scrot backend lacks those controls.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThe script works locally but fails over SSH or in CI
Check whether the process has access to an active graphical session. A terminal-only server has no physical desktop for this package to capture. Use a real logged-in session or a separately configured virtual display, and verify that your CI account has permission to access it.
The output is in the wrong format
JPG is the default. Set format: 'png' and use a matching .png filename. Only png and jpg are documented values.
The wrong monitor is captured
Call listDisplays() immediately before capture, log each id and name, and pass the selected ID as screen. Recheck after docking, undocking, or changing display settings.
The file cannot be written
Create the parent directory, use an absolute path, and verify write permissions for the Node process. When using filename, log the resolved path returned by the Promise.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Operational and cost considerations
Each capture is a local operation that consumes CPU, memory, and disk or network bandwidth according to the image size and your downstream handling. Avoid launching many simultaneous captures if the desktop or backend becomes unresponsive; queue jobs and release Buffers after upload. For recurring jobs, include timestamps or unique IDs in filenames to avoid overwriting prior evidence.
The package itself is installed software rather than a metered hosted API. Your costs are therefore the machine, storage, and any image-processing or infrastructure services you add. Its scope is a visible local desktop, so it is a poor fit for server-side capture of arbitrary public URLs.
Or skip the browser setup: ScreenshotNeo
If your goal is a clean screenshot of a website rather than the physical desktop, ScreenshotNeo is the first alternative to try: it removes consent banners, newsletter popups, and chat widgets before capture, and bills only clean shots.
One GET request returns PNG, JPEG, WebP, or a PDF. The API base is https://api.screenshotneo.com/v1/shot. See the ScreenshotNeo documentation for the full option list.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' })
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`)
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const data = Buffer.from(await res.arrayBuffer())
require('node:fs').writeFileSync('shot.webp', data)ScreenshotNeo’s response headers identify the page verdict and whether the request was billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Plans include 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots. Every plan includes every feature, including full-page lazy-image loading, CSS-selector element capture, device presets, custom CSS and JavaScript, request blocking, authentication headers and cookies, geolocation, signed links, webhooks, bulk capture, caching, and PDF controls.
Sign up for the free ScreenshotNeo plan to get 1,000 screenshots a month without a card.
Frequently Asked Questions
Can screenshot-desktop capture only one application window?
The documented API covers whole-display capture, selecting a display with screen, or capturing all displays with all(). It does not document window-level selection.
Does the package run in a Docker container by itself?
Not necessarily. A container still needs access to a graphical display and the required Linux capture dependencies; the package does not create that display environment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Which Node.js module syntax does the package example use?
The documented examples use CommonJS with require('screenshot-desktop'). If your project is ESM, adapt the import according to your Node.js configuration and verify it against the installed release.
Can I rely on display IDs remaining unchanged forever?
No stability guarantee is stated. Enumerate displays at runtime when monitor arrangements can change.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
