Installation

Requirements

• Python 3.10 or later
• macOS, Linux, or Windows (WSL recommended on Windows)

Quick start

Clone the repository and install:

git clone https://github.com/zen-logic/file-hunter.git
cd file-hunter
python -m venv venv
source venv/bin/activate   # on Windows: venv\Scripts\activate
pip install -r requirements.txt

Running

Start the server:

./filehunter

Or equivalently:

python -m file_hunter

The server starts on http://127.0.0.1:8000 by default. Open it in any browser.

Command-line options

./filehunter --host 0.0.0.0 --port 9000   # bind to all interfaces, custom port
./filehunter --demo                         # start with test data

First run

When no users exist in the database, File Hunter shows a setup screen where you create the first user account. After logging in you’ll see the main interface with an empty catalog.

To get started, click the + button in the toolbar (or press N) to add your first location. Point it at any folder — a USB drive mount, a local directory, a network share — and start a scan.

Demo mode

Run with --demo to create a testdata/ directory with sample files and locations. This is useful for exploring the UI before pointing it at real storage. Delete testdata/ and file_hunter.db to reset.

Running as a systemd service

On Linux, you can run File Hunter as a background service that starts automatically on boot. Create a unit file:

sudo nano /etc/systemd/system/filehunter.service

Paste the following, adjusting paths and user to match your setup:

[Unit]
Description=File Hunter
After=network.target

[Service]
Type=simple
User=<your-user-name>
WorkingDirectory=/home/<your-user-name>/file-hunter
ExecStart=/home/<your-user-name>/file-hunter/venv/bin/python -m file_hunter --host 0.0.0.0
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable filehunter
sudo systemctl start filehunter

Useful commands:

sudo systemctl status filehunter    # check status
sudo journalctl -u filehunter -f    # follow logs
sudo systemctl restart filehunter   # restart after update

Upgrading

Pull the latest code and restart:

git pull
pip install -r requirements.txt
./filehunter

Database migrations are automatic — new columns and indexes are added on startup without data loss.

Installing Pro

After purchasing a Pro license, install it from within File Hunter:

1. Go to Settings (gear icon in the toolbar)
2. Click “Upgrade to Pro”
3. Enter your license key
4. The Pro package downloads and installs automatically
5. Click “Restart Now”

For air-gapped machines, download the package and use the “Upload package” option in the same dialog.