ReclaimSpace Docs

Usage

Here are some common ways to use reclaimspace:

Interactive Mode (Default)

This is the default behavior. It lists all the folders, and you can select which ones to delete.

Copynpx reclaimspace

Auto-Delete Everything

This will find all reclaimable items and delete them automatically without confirmation.

Copynpx reclaimspace --yes

Dry Run (Preview)

This will list all the items that can be deleted but won't actually delete anything.

Copynpx reclaimspace --dry

Scan a Specific Folder

You can specify one or more directories to scan.

Copynpx reclaimspace <foldername>

Display Version Number

This will display the version number of the tool.

Copynpx reclaimspace --version

Display Help Message

This will display the help message with all available options.

Copynpx reclaimspace --help

Combine Flags and Folders

You can combine any of the flags with a specific folder.

Copynpx reclaimspace --yes my-project

Enable Build Analysis

This will enable build analysis logs.

Copynpx reclaimspace --build-analysis

Ignore Certain Folders Permanently (Global)

You can permanently exclude folders from the scan by providing a comma-separated list of patterns. This will update the global .reclaimspacerc file (in %APPDATA%\reclaimspace\ on Windows, ~/Library/Application Support/reclaimspace/ on macOS, or ~/.config/reclaimspace/ on Linux) using the --save or -s flag.

Copynpx reclaimspace --ignore "node_modules,dist" --save

Include Only Specific Folders

You can specify a comma-separated list of patterns to include in the scan. When this flag is used, only folders matching these patterns will be considered.

Copynpx reclaimspace --include "my-custom-build,temp-files"

Deep Clean Package Manager Caches

This will clear caches for npm, pnpm, yarn, pip, and other detected package managers. When cache size is unchanged after cleaning, a descriptive reason is shown explaining why. Can be combined with other flags.

Copynpx reclaimspace --deep-clean

You can also use the short flag:

Copynpx reclaimspace -dc

Combine with a full scan and auto-delete:

Copynpx reclaimspace --yes --deep-clean

Features

• Interactive Deletion: Navigate through a list of found items using arrow keys, space to select, and Enter to proceed.
• Zero Runtime Dependencies: Built from the ground up with native Node.js APIs for maximum speed and security. No node_modules at runtime!
• Categorized & Grouped: Results are grouped by type for clarity.
• Size Information: See the size of each item and the total reclaimable space.
• Concurrent Scanning: Quickly finds and processes files.
• Build Artifact Detection: Intelligently detects build folders.
• Auto-Delete Mode: Use the --yes flag to delete all found items without confirmation.
• Dry Run Mode: Use the --dry flag to see what would be deleted without actually deleting anything.
• Ignore Patterns: Exclude specific folders or patterns using a .reclaimspacerc file or the --ignore flag.
• Interactive UI: Supports 'a' to select all and 'i' to invert selection.
• Keyboard Protection: Terminal input is suppressed during deletion, preventing accidental keystrokes (like Enter) from corrupting the output.
• Build Analysis: Use the --build-analysis flag to see inferred project types and common build patterns.
• Include Patterns: Use the --include flag to scan only folders matching specific patterns, overriding defaults.
• Global Config: Ignore patterns can be saved globally via --save, applying across all projects without per-project .reclaimspacerc files.
• Deep Clean Mode: Use the --deep-clean (-dc) flag to clear package manager caches (npm, pnpm, yarn, pip) for even more reclaimed space. Shows descriptive reasons when cache size is unchanged.
• Windows Stability: Includes built-in retry logic for locked files (EBUSY/EPERM), ensuring smooth cleanup on Windows systems.
• Smart Error Handling: Clear, actionable messages for resource-busy errors, helping you identify which applications to close.
• Cool Logo: Displays a cool logo when you run the tool.

Configuration

Per-Project Ignore Patterns

Create a .reclaimspacerc file in the root of your project to specify folders and patterns to ignore:

Copy# Ignore all node_modules folders
node_modules

# Ignore a specific build folder
my-project/dist

Global Ignore Patterns

You can also save ignore patterns globally so they apply to every project. Use the --ignore flag together with --save (or -s):

Copynpx reclaimspace --ignore "node_modules,dist" --save

Global patterns are stored in a .reclaimspacerc file inside the platform-specific config directory:

• Windows: %APPDATA%\reclaimspace\.reclaimspacerc
• macOS: ~/Library/Application Support/reclaimspace/.reclaimspacerc
• Linux: ~/.config/reclaimspace/.reclaimspacerc

Default Ignore Patterns

The tool automatically excludes common system and editor directories from scanning:

System: Program Files, Applications, System, Library, usr, var, etc, opt

Editors/IDE: .vscode, .cursor, .idea, .sublime-project, .atom

Package Managers: .pnpm-store

Other: .vitest-attachments, src, app, lib, components, pages, assets

Detected Items

reclaimspace detects the following categories:

1. Node Modules
   • node_modules
2. Build/Cache Folders
   • .next, dist, build, storybook-static, .nuxt, .output, .svelte-kit, .angular, out, .expo, .turbo, .cache, .shopify, .react-router, .tanstack, .vite-ssg-temp
   • .rollup.cache, .parcel-cache, .vite, .astro, .solid, .remix, .docusaurus, .eleventy-cache, .gatsby-cache, .eslintcache, .stylelintcache, .prettiercache, .tsbuildinfo, .swc, .nx, .wwebjs_cache, .wwebjs_auth, public/build
3. Testing/Reporting Folders
   • coverage, .nyc_output, .pytest_cache, .tox, htmlcov
4. Miscellaneous Dev Junk
   • .venv, venv, env (Python Virtual Environments)
   • __pycache__, .mypy_cache, .ruff_cache (Python caches)
   • vendor (Go/PHP dependencies)
   • .vagrant, .terraform (Infrastructure tools)

Changelog

See the CHANGELOG.md for a full history of changes and contributor credits.

Contributing

Contributions are welcome! Please read our contributing guidelines to get started.