File Unlocker

File Unlocker is a modern cross-platform tool to unlock and delete locked files on Windows and Linux.

It is available as:

• A full-featured Electron desktop application (with GUI)
• A Node.js module (for programmatic use in your scripts and apps)
• A Command Line Interface (CLI) tool (for terminal and automation)

---

Support the Project

File Unlocker is free and open source (MIT license). If it saved you time, please consider supporting its development:

• 💖 Donate via GitHub Sponsors
• ⭐ Star the repo on GitHub
• 🌐 Explore more tools at edenware.app

Your support keeps the project maintained, updated and free for everyone.

---

Quick Start

As a Desktop App (Electron GUI)

npm install
npm start

Or run the packaged executable for your platform.

As a CLI Tool

npx file-unlocker <file> [options]
# or
node cli.js <file> [options]

As a Node.js Module

File Unlocker supports both ESM and CommonJS module formats:

CommonJS

const { unlockFile, deleteFile, getProcessesUsingFile } = require('file-unlocker');

// Unlock file
unlockFile('file.txt').then(result => {
  console.log(result);
});

// Delete file (unlocks first if needed)
deleteFile('file.txt', { useRecycleBin: true }).then(result => {
  console.log(result);
});

// Check processes using file
getProcessesUsingFile('file.txt').then(processes => {
  console.log(processes);
});

ESM (ES Modules)

import { unlockFile, deleteFile, getProcessesUsingFile } from 'file-unlocker';

// Unlock file
const result = await unlockFile('file.txt');
console.log(result);

// Delete file (unlocks first if needed)
const deleteResult = await deleteFile('file.txt', { useRecycleBin: true });
console.log(deleteResult);

// Check processes using file
const processes = await getProcessesUsingFile('file.txt');
console.log(processes);

---

Overview

File Unlocker features a modular architecture that allows you to use it in three ways:

1. Graphical Interface (Electron) – Complete desktop application
2. Command Line Interface (CLI) – Terminal tool
3. Node.js Module – Library for use in other projects

Features

• Modern and intuitive interface
• System Tray – Minimizes to system tray
• Explorer Context Menu – Right-click on files
• Advanced unlocking strategies:
  • Native PowerShell
  • Direct Windows API
  • File lock detection
• Automatic process analysis
• Unlock only or unlock and delete
• Always moves to recycle bin (safe)
• Drag & drop files
• Keyboard shortcuts

File Structure

UNLOCKER/
├── main.js                 # Smart entry point
├── electron-main.js        # Electron-specific logic
├── cli.js                  # Command line interface
├── lib/
│   ├── native-windows-api.js   # Main module with all business logic (CommonJS)
│   └── file-unlocker.mjs       # ESM wrapper (re-exports the CommonJS API)
├── index.html              # Graphical interface
├── renderer.js             # Frontend logic
├── styles.css              # Interface styles
├── assets/                 # Icons and resources
├── locales/                # Translation files
└── package.json            # Project configuration

Building for Distribution

The module is published to npm (file-unlocker) with both CommonJS and ESM entry points resolved via the exports field — no build step is needed:

• CommonJS: require('file-unlocker') → lib/native-windows-api.js
• ESM: import { unlockFile } from 'file-unlocker' → lib/file-unlocker.mjs

npm publish   # publishes the module + CLI to npm

How to Use

1. Graphical Interface (Electron)

npm start

Starts the desktop application with complete graphical interface.

2. Command Line Interface (CLI)

# Via npx (recommended)
npx file-unlocker <file> [options]

# Via node directly
node cli.js <file> [options]

# Examples
npx file-unlocker "file.txt"                    # Just unlock
npx file-unlocker "file.txt" --delete          # Unlock and delete
npx file-unlocker "file.txt" --recycle-bin     # Move to recycle bin
npx file-unlocker "file.txt" --force-kill      # Force unlock
npx file-unlocker "file.txt" --check-only      # Check processes

3. Node.js Module

File Unlocker supports both ESM and CommonJS module formats:

CommonJS

const { 
  unlockFile, 
  deleteFile,
  getProcessesUsingFile, 
  killProcess, 
  moveToRecycleBin 
} = require('file-unlocker');

// Unlock file
unlockFile('file.txt').then(result => {
  console.log(result);
});

// Delete file (unlocks first if needed)
deleteFile('file.txt', { useRecycleBin: true }).then(result => {
  console.log(result);
});

// Check processes using file (or directory – passing a folder will
// search for handles to any file inside it)
getProcessesUsingFile('file.txt').then(processes => {
  console.log(processes);
});

// Kill specific process
killProcess(1234).then(result => {
  console.log('Process terminated:', result);
});

// Move to recycle bin
moveToRecycleBin('file.txt').then(result => {
  console.log('File moved to recycle bin:', result);
});

ESM (ES Modules)

import { 
  unlockFile, 
  deleteFile,
  getProcessesUsingFile, 
  killProcess, 
  moveToRecycleBin 
} from 'file-unlocker';

// Unlock file
const result = await unlockFile('file.txt');
console.log(result);

// Delete file (unlocks first if needed)
const deleteResult = await deleteFile('file.txt', { useRecycleBin: true });
console.log(deleteResult);

// Check processes using file
const processes = await getProcessesUsingFile('file.txt');
console.log(processes);

// Kill specific process
const killResult = await killProcess(1234);
console.log('Process terminated:', killResult);

// Move to recycle bin
const moveResult = await moveToRecycleBin('file.txt');
console.log('File moved to recycle bin:', moveResult);

Automatic Environment Detection

The main.js automatically detects the execution environment:

• Electron: Detects process.versions.electron and loads electron-main.js
• CLI: Detects command line arguments and loads cli.js
• Module: When required as a module, exports only business functions

Advantages of the New Architecture

1. Separation of Responsibilities

• lib/native-windows-api.js: Contains all business logic (process detection, unlocking, etc.)
• electron-main.js: Manages only the graphical interface and Electron events
• cli.js: Manages only the command line interface
• main.js: Smart entry point that redirects according to the environment

2. Code Reuse

• The same unlocking logic is used in both GUI and CLI
• Changes in business logic automatically affect all interfaces

3. Easy Maintenance

• Each file has a specific responsibility
• Easier debugging - GUI problems are isolated from business logic
• Tests can focus on business logic independently of the interface

4. Flexibility

• Can be used as a library in other projects
• CLI works without Electron dependencies
• GUI can be easily modified without affecting the logic

Module API

Main Functions

// Unlock file
unlockFile(filePath, options)

// Delete file (unlocks first if needed)
deleteFile(filePath, options)

// Get processes using file
getProcessesUsingFile(filePath)

// Move to recycle bin
moveToRecycleBin(filePath)

// Kill process
killProcess(pid)

// Check admin privileges
isRunningAsAdmin()

Options

// Options for unlockFile
const unlockOptions = {
  forceKill: false        // Force unlock by killing processes
};

// Options for deleteFile
const deleteOptions = {
  useRecycleBin: false,   // Move to recycle bin instead of permanent delete
  forceKill: false        // Force unlock by killing processes before deleting
};

Module Compatibility

File Unlocker is distributed on npm and provides both formats through the exports field:

• CommonJS: require('file-unlocker') → lib/native-windows-api.js
• ESM: import { unlockFile } from 'file-unlocker' → lib/file-unlocker.mjs

Testing Module Compatibility

You can test both formats locally:

# Test CommonJS
node -e "const { unlockFile } = require('./lib/native-windows-api.js'); console.log('CommonJS works!');"

# Test ESM
node -e "import('./lib/file-unlocker.mjs').then(m => console.log('ESM works!'));"

Installation

npm install
npm start

Build

npm run build

Development

Development Structure

1. Business Logic: Modify only lib/native-windows-api.js
2. Graphical Interface: Modify electron-main.js, index.html, renderer.js, styles.css
3. CLI Interface: Modify cli.js
4. Entry Point: Modify main.js only if necessary

Testing

# Test CLI
node cli.js --help
node cli.js "test.txt" --check-only

# Test module
node -e "const f = require('./lib/native-windows-api.js'); console.log('Module OK:', typeof f.unlockFile);"

# Test GUI
npm start

Compatibility

• Windows: Full support (GUI, CLI, module)
• Linux: Full support (GUI, CLI, module)
• macOS: Basic support (CLI, module)

Dependencies

• Electron: Only for graphical interface
• Node.js: Base runtime for all functionalities

The published npm module (file-unlocker) has zero runtime dependencies. The native addon (handle_checker, Windows-only) is optional and only built for development; at runtime the module falls back to built-in methods.

Build and Distribution

# Build for all platforms
npm run build:all

# Specific build
npm run build:win
npm run build:linux

# Distribution
npm run dist

Requirements

• Windows 10 or higher
• Node.js 16+
• npm or yarn

Troubleshooting

Permission Error

• Run the application as administrator
• Check if the file is not in use by another process

Process Not Detected

• Some processes may not be detected automatically
• Use the "Refresh" option for new analysis

The new architecture makes File Unlocker more modular, reusable, and easy to maintain, allowing it to be used flexibly in different contexts.