QuickFind v0.8.59

Lightning-fast file search for Windows, powered by NTFS MFT + USN Journal.

An open-source alternative to Voidtools Everything, built with Python and PyQt6 for extensibility and customization.

Features

Core Engine

• Instant indexing via NTFS Master File Table (MFT) direct read with parallel scanning
• FAT32/exFAT/ReFS support for external drives and Dev Drives via recursive os.scandir walk
• SMB network share indexing for UNC roots with optional Windows Credential Manager-backed credentials
• Optional link traversal follows symbolic links and junctions in directory-walk mode with visited-target loop protection
• Global exclude rules filter indexed results by glob, regex, or NTFS attribute mask; directory-walk indexes skip excluded folders before descent
• Extended NTFS metadata surfaces reparse tags and extended-attribute presence in result tooltips, preview info, and cache records
• USN Journal V2/V3/V4 support — V3/V4 with 128-bit file IDs for ReFS compatibility
• Real-time updates via USN Change Journal monitoring (NTFS) with durable per-batch journal checkpoints, plus configurable periodic rescan (FAT/exFAT/ReFS)
• Cross-platform engine boundary keeps Windows on MFT/USN while Linux/macOS index configured POSIX roots with os.scandir, SQLite cache, and Watchdog native monitoring (inotify/FSEvents); macOS also has a Spotlight fallback helper
• Non-admin fallback — gracefully degrades to os.scandir when UAC is declined, with a persistent status-bar indicator
• SQLite FTS5 full-text search cache with WAL mode and memory-mapped I/O, gated to patched SQLite runtimes with LIKE fallback
• DB corruption recovery with automatic integrity checks and rebuild
• Sub-second search across millions of files with compiled pattern matching
• Incremental availability — search is available as soon as the first drive finishes indexing
• Minimal footprint — lightweight in-memory index with __slots__ optimization

Search

• Instant-as-you-type results with debounced search
• Smart case sensitivity — uppercase in query auto-switches to case-sensitive (fd-style); explicit case:/nocase: overrides
• Index case mode — choose smart, always case-insensitive, or always case-sensitive baseline matching
• Fuzzy matching via fuzzy: modifier — subsequence matching for typo-tolerant search
• Search history with autocomplete suggestions
• Saved query slots — bookmark queries are reusable as @slot aliases in the GUI and CLI
• Result highlighting — match substrings painted in accent color and content: previews highlight matched context lines
• Inline column filtering — per-column filter row below headers
• Regex support (regex:pattern)
• Wildcards (*.py, test?.log)
• Boolean logic — nested parentheses with NOT > implicit AND > OR precedence
• Content search — content:keyword searches cached TXT/PDF/DOCX/PPTX/EML/source-code extracted text through sandboxed per-file worker adapters, with optional Tesseract OCR fallback for image-only PDFs and a Windows IFilter/property-handler bridge for installed Windows Search extractors, cancellable background indexing, ranked snippets, root/type filters, quotas, timeout handling, and adapter diagnostics
• Archive search — archive: searches cached ZIP/7z member metadata through sandboxed per-archive workers without extracting files, invalidating when archives change
• Usage-based ranking — frequently opened files rank higher with Relevance sort
• 20 built-in search modifiers plus a programmatic plugin API for registered custom name:value modifiers
• Offline help from the Help menu with bundled search syntax, workflow, and troubleshooting cheat sheets

GUI

• Launcher popup — Ctrl+Shift+F summons a floating search bar (Wox/Flow Launcher style) with keyboard hints and empty-state feedback
• Theme packs — Catppuccin Mocha, Macchiato, Frappe, and Latte selectable from settings
• Localization — English and Spanish UI shell language packs with a persisted settings selector
• Details view with sortable columns (Name, Path, Size, Date Modified, Date Created, Type, Attributes)
• Finder-style Columns view with root/folder/item path segments and a selectable breadcrumb header
• Multi-tab search with independent query/filter/workspace/match options and a keyboard-navigable tab switcher dialog
• Bounded native icon cache keeps file-type icons responsive without unbounded memory growth
• Column visibility — right-click header to show/hide columns, persisted in settings
• Keyboard navigation — Enter open, Delete recycle, F2 rename, Ctrl+Enter open folder
• Thumbnail view for visual browsing
• Preview pane for text files, images, and file info with matched-line context for content: searches
• Quick preview popover opens the selected result in a floating preview from details, columns, or thumbnail views
• Inline file diff compares two selected text files with a bounded unified-diff dialog
• Filter bar with built-in filters (Audio, Video, Image, Document, Executable, Compressed, Folder) + custom filters
• Bookmarks — save/restore search, filter, match options, and multi-root workspace state
• Context menu — Open, Open Path, Open With (VS Code, VSCodium, Notepad++, Obsidian), opt-in Open/Save dialog Quick Switch, Copy Name/Path, Terminal Here (CMD/PowerShell/WT), Delete to Recycle Bin with status/tray feedback and recovery hint, Properties
• System tray with minimize-to-tray and close-to-tray
• Index diagnostics from the Tools menu with cache integrity, per-drive online/offline/stale state, per-drive refresh, service heartbeat, content cache size/extractor breakdowns, redacted support bundle export, and recovery buttons
• Dark title bar via DwmSetWindowAttribute on Windows 10/11
• Accessibility — narrator labels on settings, results, preview, diagnostics, and status surfaces; explicit keyboard flow from filters to search to results; rendered/offscreen smoke coverage for critical labels and focusable controls; focus-visible states on interactive elements

Advanced

• HTTP/HTTPS server for remote web browser access with TLS certificate support, Bearer/Basic/session-cookie authentication, secure same-origin browser sessions, read-only result cards, structured JSON search, API docs, OpenAPI export, all/files/folders filters, result caps, per-IP rate limiting (60 req/min), XSS protection (CSP headers + html.escape), no-store browser headers, and sticky-header web UI
• Windows service mode for background indexing/monitoring with GUI status heartbeat over localhost IPC
• .quickfindignore files — place in any directory with glob patterns to exclude files/folders from indexing (like .gitignore)
• EFU file lists for importing external Everything file lists
• External EFU refresh scheduler reloads configured file lists on an interval and replaces each EFU source cleanly
• CLI tool (es.py) with full search syntax, saved @slot query aliases, CSV/JSON output, and DB cache for instant results
• Per-drive rescan intervals and startup delay — configure refresh cadence and wait for late-mounted removable or virtual drives
• Export/import settings — save and restore schema-versioned configuration as validated JSON with pre-replacement backups and invalid-import rollback
• Open/Save dialog Quick Switch — optional Windows integration that sends selected folders to the active common file dialog
• Search modifier plugin API registers custom modifier parsers, aliases, and per-entry predicates through core.search.SearchModifierPlugin
• Everything import hardening — malformed CSV rows and invalid JSON are rejected before atomic filter/bookmark replacement
• Log rotation — RotatingFileHandler with 5 MB max and 3 backups
• 577 automated tests covering startup dependency handling, cross-platform engine selection, POSIX root indexing, build/runtime matrix reporting, support bundle redaction/export, settings schema migration/rollback, recoverable delete feedback, rendered accessibility smoke coverage, release artifact checks, SQLite/FTS5 version gates, Finder-style path columns, quick preview popovers, custom search modifier plugins, theme packs, localization, accessibility metadata, offline help docs, inline file diff, Open With discovery, saved query slot expansion, bookmark workspace roots, nested boolean query parsing, hash duplicate detection, broken link/shortcut finders, Git dirty worktree filtering, USN checkpoint durability, remote REST docs/OpenAPI, remote web UI cards/filters, remote auth/CORS hardening, remote same-origin session checks, SMB/UNC network-share indexing, EFU refresh scheduling, EML/source-code content extraction, optional PDF OCR/Windows IFilter fallback, parser worker isolation, preview matched-line highlighting, Everything import validation, index/cache/service diagnostics, removable-drive stale state, dialog Quick Switch helpers, link/junction traversal loop guards, global exclude rules, reparse/EA metadata persistence, case-mode matching policy, content indexing jobs/quotas/diagnostics, content search ranking/snippets, search parsing, archive metadata caching, content adapters/cache, service IPC, duplicate detection, MFT record parsing, privilege lifecycle, settings validation, index mode UI state, results-view cache bounds, cache helpers, remote server configuration, MSIX/App Installer/winget packaging, and ignore patterns
• PyInstaller and MSIX build script for single-file, single-folder, App Installer, and winget distribution

Requirements

• Windows 10/11 for NTFS MFT/USN indexing; Linux/macOS for POSIX root indexing
• Python 3.10+
• Administrator privileges recommended (for NTFS MFT access; falls back to os.scandir without admin)

Supported Runtime Matrix

Component	Supported	Tested in v0.8.59
OS	Windows 10/11	Windows 10.0.26100
Python	3.10+	3.11.9
SQLite	LIKE fallback on older runtimes; FTS5 enabled on patched SQLite 3.53.2+	3.45.1 with FTS5 disabled
PyQt6 / Qt6 / sip	pinned in requirements.txt	6.11.0 / 6.11.1 / 13.11.1
pywin32	pinned in requirements.txt	312
Content/archive adapters	pinned in requirements.txt; Windows Search IFilter/property extraction when pywin32 and installed handlers are available	pdfplumber 0.11.10, py7zr 1.1.3, python-docx 1.2.0, python-pptx 1.0.2, pywin32 312
Native file watchers	Watchdog native observers for Linux inotify/macOS FSEvents	watchdog 6.0.0
Build tooling	pinned in requirements.txt; no build-time auto-install	PyInstaller 6.21.0

Quick Start

# Clone the repo
git clone https://github.com/SysAdminDoc/QuickFind.git
cd QuickFind

# Install dependencies
pip install -r requirements.txt

# Run (attempts admin elevation, falls back gracefully)
python quickfind.py

QuickFind never installs dependencies at startup. Source runs require the dependencies above to be installed first; frozen builds must bundle them through build.py.

SQLite FTS5 is enabled only on SQLite 3.53.2 or newer. Older runtimes keep working through LIKE-based entry and content search fallback.

On Linux/macOS, QuickFind indexes the user's home directory by default. Set QUICKFIND_INDEX_ROOTS to an os.pathsep-separated root list before launch to index specific POSIX roots.

CLI Usage

# Basic search (uses DB cache for instant results)
python cli/es.py "*.py"

# Force reindex (bypass cache)
python cli/es.py --reindex "*.py"

# Regex search for log files
python cli/es.py -r "error.*\.log$"

# Find large MP4 files, output as JSON
python cli/es.py --json "size:>100mb ext:mp4"

# Files only, sorted by date modified
python cli/es.py -f -s dm "report"

# Search specific drives (Windows) or POSIX roots (Linux/macOS)
python cli/es.py --drives C,D "*.docx"

# Reuse a saved bookmark query slot
python cli/es.py @logs error

Service Mode

# Install the background index service
python quickfind.py --install-service

# Start/stop/remove the service
python quickfind.py --start-service
python quickfind.py --stop-service
python quickfind.py --remove-service

Remote API

When the HTTP/HTTPS server is enabled, browser docs are available at /api/docs and the OpenAPI 3.1 export is available at /openapi.json. If an auth token is configured, send Authorization: Bearer <token>, use HTTP Basic with the token as the password, or sign in through the browser form to receive the same-origin session cookie.

curl -H "Authorization: Bearer <token>" "http://127.0.0.1:8080/api/search?q=report&type=files&max=25"

/api/search returns structured results metadata plus cards/rows HTML used by the read-only web UI.

Build

# Build single-folder distribution
python build.py

# Build single-file exe
python build.py --onefile

# Build signed MSIX package and winget manifests
python build.py --msix --winget

# Validate local release metadata and GitHub release assets
python build.py --release-check

# Pre-upload local-only check for unsigned packages
python build.py --release-check --skip-remote --allow-unsigned

# Clean build artifacts
python build.py --clean

Build output prints the tested runtime matrix before invoking PyInstaller. If PyInstaller is missing, install the pinned requirements instead of relying on an automatic build-time install. MSIX signing uses QUICKFIND_SIGN_PFX and optional QUICKFIND_SIGN_PFX_PASSWORD; without a PFX, build.py --msix asks signtool to auto-select a signing certificate from the local store. The release check validates README/version drift, MSIX manifest version, MSIX signature status, App Installer URLs, winget URL/hash metadata, and GitHub release asset reachability.

Search Syntax

Syntax	Description
foo bar	Files containing both "foo" AND "bar"
foo | bar	Files containing "foo" OR "bar"
!temp	Exclude files containing "temp"
foo (bar | baz)	Nested boolean grouping; NOT > AND > OR
"exact phrase"	Match exact phrase
*.py	Wildcard matching
regex:^test\d+	Regex matching
fuzzy:qickfind	Fuzzy subsequence matching
case:FooBar	Case-sensitive match
path:src\utils	Match in full path
file: / folder:	Files or folders only
ext:py;js;ts	Filter by extension
size:>1mb	Size greater than 1 MB
size:100kb..5mb	Size range
dm:today	Modified today
dm:>2024-01-01	Modified after date
dc:thisweek	Created this week
content:TODO	Search inside cached TXT/PDF/DOCX/PPTX/EML/source and optional Windows IFilter content
@logs	Expand a saved bookmark query slot
len:>20	Filename length > 20 chars
attrib:rh	Read-only + hidden
parent:node_modules	Parent directory filter
dupe:	Find duplicate filenames
duplicate:hash	Find duplicate files by SHA-256 content hash
broken:link / broken:shortcut	Find broken reparse links or .lnk targets
git:dirty	Find files inside dirty Git worktrees
archive:report	Find files named report inside ZIP/7z archives

Smart case: Queries with uppercase letters automatically use case-sensitive matching. All-lowercase queries match case-insensitively. Override with case: or nocase:.

Custom Modifier Plugins

Python integrations can register custom name:value search modifiers without patching the parser:

from core.search import SearchModifierPlugin, register_modifier_plugin

register_modifier_plugin(SearchModifierPlugin(
    names=("prefix",),
    match=lambda entry, index, value, parsed: entry.name.startswith(value),
))

Registered modifiers support aliases, optional parser callbacks that return extra search terms, and optional per-entry predicates. Custom modifier queries always use the in-memory search path so predicates are applied to every candidate.

.quickfindignore

Place a .quickfindignore file in any directory to exclude matching files and folders from indexing. Uses glob patterns, one per line (like .gitignore):

node_modules
*.pyc
.git
__pycache__
.venv

Lines starting with # are treated as comments.

Architecture

QuickFind/
  quickfind.py              # Entry point (bootstrap + admin elevation + fallback)
  build.py                  # PyInstaller packaging script
  requirements.txt          # pip dependencies
  core/
    ntfs.py                 # NTFS MFT/USN via ctypes + ReFS/Dev Drive support
    index.py                # In-memory index + USN monitor + deferred path resolution
    cache.py                # SQLite FTS5 cache + integrity check + search history + content/archive cache
    search.py               # Search engine with built-in/plugin modifiers + fuzzy/content matching
    archives.py             # ZIP/7z member enumeration/cache adapter for archive: searches
    content/                # TXT/PDF/DOCX/PPTX extraction adapters + content indexing jobs
    utils.py                # Shared utilities (size parsing)
    file_list.py            # EFU file list import/export
    hidden_paths.py         # Per-filter hidden path management
    everything_import.py    # Validated Everything config file import
  gui/
    main_window.py          # Main window (menus, toolbar, layout, multi-tab search)
    launcher_popup.py       # Floating launcher search bar (Ctrl+Shift+F)
    results_view.py         # Table model + highlight delegate + column filters
    preview_pane.py         # Text/image/info preview
    filters.py              # Filter bar + custom filter editor
    bookmarks.py            # Bookmark manager + panel
    context_menu.py         # Right-click menu with shell integration
    tray.py                 # System tray + global hotkey + app icon
    settings_dialog.py      # Settings dialog with tabs + export/import
    diagnostics_dialog.py   # Index/cache/service diagnostics and recovery actions
    hidden_paths_dialog.py  # Hidden paths management dialog
    theme.py                # Selectable Catppuccin theme packs
  server/
    http_server.py          # Remote web search server + token auth + rate limiting
  service/
    windows_service.py      # pywin32 background index service
    ipc.py                  # localhost JSON status socket
  cli/
    es.py                   # Command-line search tool + DB cache
  tests/
    test_search.py          # Search parsing, modifiers, smart case, fuzzy matching
    test_archive_search.py  # ZIP/7z archive member search and cache invalidation
    test_content_search.py  # Content extraction, cache, and preview context
    test_everything_import.py # Everything CSV/JSON import validation
    test_service.py         # Service status socket and install wiring
    test_ntfs.py            # MFT record parsing, FILETIME conversion, USA fixup
    test_cache.py           # Datetime conversion, FTS5 detection
    test_index.py           # .quickfindignore pattern matching
    test_file_list.py       # EFU file loading and FILETIME parsing
  assets/
    quickfind.ico           # App icon (auto-generated on first run)

How It Works

1. MFT Scan (NTFS): Reads the NTFS Master File Table directly to enumerate all file/folder records in ~1-2 seconds per drive (parallel scanning across drives)
2. Directory Walk (FAT/exFAT/ReFS): Uses recursive os.scandir for non-NTFS drives (external USB, SD cards, Dev Drives)
3. Non-Admin Fallback: If UAC elevation is declined, falls back to os.scandir for all drives
4. Incremental Availability: Search is available as soon as the first drive finishes indexing — no waiting for all drives to complete
5. Path Resolution: Builds parent-child FRN tree to resolve full paths on demand with deferred batch resolution
6. USN Journal (NTFS): Polls the NTFS Change Journal (V2/V3/V4) every second for creates/deletes/renames/modifications
7. Periodic Rescan (FAT/exFAT/ReFS): Re-walks non-NTFS drives at configurable intervals for change detection
8. Search: Parses query modifiers, compiles matchers (regex/wildcard/substring/fuzzy/content), and filters the in-memory index — falls back to SQLite FTS5 for simple queries
9. Content Cache: TXT/PDF/DOCX/PPTX/EML/source adapters, optional OCR, and optional Windows IFilter/property handlers extract text into an on-disk SQLite FTS5 cache for faster repeated content: searches
10. DB Cache: SQLite FTS5 database persists the index for instant CLI searches and fast startup recovery
11. Service Mode: Optional Windows service keeps the index warm in the background and exposes localhost JSON status for the GUI
12. Usage Tracking: Files opened via QuickFind have their open counts tracked in SQLite for relevance-based ranking

Testing

# Run the test suite (577 tests)
python -m pytest tests/ -v

Tests cover startup dependency handling, cross-platform engine selection, POSIX root indexing, build/runtime matrix reporting, support bundle redaction/export, settings schema migration/rollback, recoverable delete feedback, rendered accessibility smoke coverage, release artifact checks, SQLite/FTS5 version gates, Finder-style path columns, quick preview geometry and thumbnail selection, custom search modifier plugins, theme packs, localization, accessibility metadata, offline help docs, inline file diff, Open With discovery, saved query slot expansion, bookmark workspace roots, nested boolean query parsing, hash duplicate detection, broken link/shortcut finders, Git dirty worktree filtering, USN checkpoint durability, remote REST docs/OpenAPI, remote web UI cards/filters, remote auth/CORS hardening, remote same-origin session checks, SMB/UNC network-share indexing, EFU refresh scheduling, EML/source-code content extraction, optional PDF OCR/Windows IFilter fallback, parser worker isolation, preview matched-line highlighting, Everything import validation, index/cache/service diagnostics, removable-drive stale state, dialog Quick Switch helpers, link/junction traversal loop guards, global exclude-rule settings, reparse/EA metadata persistence, case-mode matching policy, content indexing jobs/quotas/diagnostics, search query parsing (all modifiers), archive metadata caching, content extraction/cache, service IPC, size/date helpers, smart case sensitivity, fuzzy matching, MFT record parsing, USA fixup, USN records, cache datetime round-trip, FTS5 detection, results-view cache bounds, MSIX/App Installer/winget manifest generation, .quickfindignore pattern matching, and EFU file loading.

Security

• XSS protection: HTTP server uses html.escape() for all user-derived content with Content-Security-Policy and X-Content-Type-Options headers
• Rate limiting: Per-IP rate limiter (60 requests/minute) on the HTTP server with 429 Too Many Requests response
• HTTPS support: Optional TLS certificate/key configuration for encrypted remote search access
• Token authentication: Optional Bearer API tokens, Basic auth using the token as password, plus same-origin browser session cookies; tokens are not accepted in URLs
• Safe Win32 calls: All ctypes DLL loads use WinDLL(use_last_error=True) with complete argtypes declarations
• Atomic config saves: Settings, bookmarks, filters, hidden paths, and Everything imports use validated atomic writes to prevent corruption on crash; settings writes keep timestamped backups before replacement
• Privilege scoping: SeBackupPrivilege enabled only when needed for NTFS MFT access

License

MIT License