CLI tool
sindresorhus/trash avatar
sindresorhus/trash

trash sends Node.js deletes to the OS trash, and admits Linux support is on its way out

Move files and directories to the trash

2,664 stars82 forksJavaScriptMIT

At a glance

What is it?
trash moves files and directories to the operating system trash instead of unlinking them, and its own documentation flags an unmaintained Linux path, a silent no-op on missing files, and a Windows service account trash that no user can open.
Who is it for?
Reach for this package when a script deletes paths it assembled from a glob and you want a mistake to stay recoverable from the desktop. Walk away on Linux, where the implementation is described as unmaintained and its removal has already been announced, and in any Windows service context, where the bin is per account and the README points back at direct deletion.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 58 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • sindresorhus/trash2,664 ★ · -1
Star history
Repository2026-10-042026-11-15
sindresorhus/trash2.7k2.7k

-1 Stars in the last 42 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Linux support is scheduled for removal unless someone steps up

The README opens with a support matrix, macOS 10.12+, Linux, and Windows 8+, then immediately undercuts one third of it. The Linux implementation is described as not very good and not maintained, followed by an offer of help and a warning: if no one steps up to help maintain it, Linux support will eventually be removed. That sentence has survived across the 10.x line, and the release record backs up the other half of the picture. v10.0.1 shipped on 2025-12-07, v10.1.0 on 2026-01-25, and v10.1.1 on 2026-02-25, while the last push to the main branch is dated 2026-09-18. The package moves; the Linux path is the part standing still. Anyone planning a long lived dependency should read that note as a deprecation warning with no replacement date attached, rather than as a bug report waiting to be filed.

Missing paths and empty globs are dropped without an error

The most consequential line in the API section is the one about silence. Non existent files and glob patterns that match nothing are silently ignored, and the documentation adds the instruction directly: if you need to know whether files were actually trashed, check for their existence beforehand. That puts the verification burden on the caller, before the call rather than after it. A cleanup script that passes a list built from a directory scan receives no signal when that listing was stale, when a pattern was typed with the wrong extension, or when a quoting layer ate a wildcard. The returned Promise resolves either way, so a catch block will not catch this. Input is typed as string | string[], and the glob option defaults to true, which means pattern matching happens inside the library rather than in your shell.

Four backends behind one call: macos-trash, XDG, Recycle Bin, WSL

The Info section maps platforms to implementations, and that mapping is where most of the behavioural difference lives. macOS goes through macos-trash. Linux follows the XDG spec, so the trash directory location is not a project decision. Windows uses recycle-bin. WSL is the odd one out: files moved from a Linux distribution running under the Windows subsystem land in the Windows Recycle Bin rather than anywhere inside the distribution. That case is worth stating plainly, because a shell first script running under WSL leaves its files somewhere the Linux side has no command for, and the restore path runs through the Windows shell instead. The publish list in package.json is three entries wide, index.js, index.d.ts, and lib, so the platform branching lives inside lib rather than at the top level and a consumer only ever imports the default export.

The two platform modules the README names are not in package.json

Here is a discrepancy worth settling before you pin a version. The README names macos-trash for macOS and recycle-bin for Windows, and neither package appears among the nine runtime dependencies declared in package.json. Those nine are @stroncium/procfs, chunkify, globby, is-path-inside, move-file, p-map, powershell-utils, wsl-utils, and xdg-trashdir. The manifest as published shows no optionalDependencies block and no peerDependencies block either, so nothing in the manifest explains how the two named modules reach an installation. Whatever the arrangement is, the dependency names that do line up with the platform claims are informative on their own: xdg-trashdir and wsl-utils sit beside the Linux and WSL lines above, and powershell-utils sits beside the Windows one.

Windows service accounts write to a recycle bin no user can open

The README carries a second FAQ entry, and it is the one that bites production deployments. When the process runs as the Windows SYSTEM account or as another service account, files move into that account's recycle bin. The example given is C:\$Recycle.Bin\S-1-5-18\ for SYSTEM, where S-1-5-18 is the security identifier for Local System. Those files are not visible in the normal user's recycle bin and, in the documentation's own wording, may accumulate over time. The remedy offered is blunt: for service contexts, consider using direct file deletion instead. That inverts the library's main advantage, because the reversibility it sells is exactly what a scheduled task, a CI runner, or a Windows service cannot see or use. Check which account your scheduled job runs under before assuming the call is recoverable.

Eight gaps between mv and a real trash call

mv is the first question any engineer asks, and the README answers it point by point. Eight gaps separate a rename call from a trash call. mv is not cross platform, so it does not exist everywhere this library is expected to run. Moving to trash is not just about moving a file into a directory named trash. On every operating system you run into file conflicts, which is the exact condition the platform trash mechanisms exist to resolve. The user cannot easily restore the file afterwards, and restoring is the point of the exercise. It will not work on an external drive. The trash directory location varies between Windows versions. Linux publishes a specification for that layout, which a hand written implementation would have to track. And on macOS you lose Put back, the feature that returns an item to the precise path it came from.

The install surface is two npm commands and a separate CLI package

The library and its command line tool are two different packages, which trips up anyone expecting a binary to appear alongside the library. Installing the module is the ordinary call:

sh
npm install trash

The trash command needs a global install of its own:

sh
npm install --global trash-cli

The documentation also links empty-trash for clearing the bin and del for permanent deletion, so a cleanup script that needs all three ends up with three dependencies. The manifest settles the module format: package.json sets type to module, the exports map points types at ./index.d.ts and default at ./index.js, and there is no require condition anywhere in it. The engines field asks for node >=20, so what gets published is ESM only. The usage example is worth copying in full, because it shows the two patterns that matter, an array of globs plus a negation that keeps !rainbow.png out of the bin while the rest go in:

js
import trash from 'trash';

await trash(['*.png', '!rainbow.png']);

The test suite drives the real trash, with a 120 second timeout

The test script in package.json reads xo && node --test --test-timeout=120000 && tsd. Two things follow from that single line. The tests exercise the actual operating system trash rather than a stub, since the only way to confirm a file moved is to move it, and the two minute timeout exists because real filesystem moves and real trash directories are slow. Contributors therefore need a desktop session with a writable bin, not a headless container. Consumers should read the same line as a boundary on where this library runs at all: any environment with no trash directory behind the user account sits outside what the suite covers, which is a good deal of container and CI work.

Editorial conclusion

Reach for this package when a script deletes paths it assembled from a glob and you want a mistake to stay recoverable from the desktop. Walk away on Linux, where the implementation is described as unmaintained and its removal has already been announced, and in any Windows service context, where the bin is per account and the README points back at direct deletion. Before pinning a version, compare the nine runtime dependencies in package.json against the platform modules the documentation names, confirm the process runs as a user rather than SYSTEM, and set the glob option to false if you would rather hand the library literal paths than patterns.

Frequently asked questions

Is trash a drop-in replacement for fs.unlink, del, and rimraf?

No. Those three permanently delete files, while this library moves them to the operating system trash, which the project calls much safer and reversible. The difference only shows up after a delete turns out to be wrong: one removes the file for good, the other leaves it recoverable from the desktop.

What does trash do with files on WSL?

On WSL, files are moved to the Windows Recycle Bin rather than to a Linux trash directory. macOS goes through macos-trash, Linux follows the XDG spec, and Windows uses recycle-bin, so the WSL case lands in the Windows implementation.

Will trash tell me when a path does not exist?

No. Non existent files and glob patterns that match nothing are silently ignored, and the returned Promise resolves either way. If you need to know whether files were actually trashed, check for their existence beforehand.

Why does package.json list fewer dependencies than the documentation names?

The documentation names macos-trash and recycle-bin as the macOS and Windows implementations, and neither appears among the nine runtime dependencies in package.json, which also shows no optionalDependencies and no peerDependencies block. Both modules are linked from the Info section instead of from the manifest.

Can trash be relied on under a Windows service account?

Files move to that account's own recycle bin, for example C:\$Recycle.Bin\S-1-5-18\ when running as SYSTEM. Those files are not visible in the normal user's recycle bin and may accumulate over time, and the documentation suggests direct file deletion for service contexts instead.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. Releases
  5. sindresorhus/trash on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sindresorhus-trash.svg)](https://hysenlabs.com/projects/sindresorhus-trash)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sindresorhus-trash.svg)](https://hysenlabs.com/projects/sindresorhus-trash)

Was this useful?