FileShare

🌐 English · 한국어

A lightweight file-sharing utility that automatically syncs folders between PCs on the same office network (LAN).

Run this one program on each PC: it serves your shared folder to colleagues and pulls their shared folders onto your PC automatically. No separate server, no cloud, no login required.

---

Why use it — great for the office

How do you hand a file to a coworker today?

• Chat / email attachments — hit size limits, and everyone re-downloads manually
• USB drives — often blocked by security policy, easy to lose
• External cloud (Drive, etc.) — your files leave the company; accounts and permissions to manage
• Manual network shares (SMB) — fiddly permissions and firewall rules, re-setup whenever people change

FileShare fills the gap between these.

	FileShare
Stays on-premise	Files never leave your LAN. No internet needed
No accounts/cloud	Zero logins, sign-ups, or external dependencies
Simple to install	Just needs Python. Same file + one config per PC
Auto-sync	Drop a file in your share folder and it copies to peers within seconds
Deletions propagate	Files removed from the source are cleaned up on receivers (one-way mirror)
Lightweight	Built on the standard-library HTTP server. Runs quietly in the background
Cross-platform	Tray icon on Windows, daemon (systemd) on Linux

Good for: distributing shared team templates/resources, sharing design & video deliverables, circulating build artifacts, handing out meeting docs, mirroring files between a dev PC and a test PC.

⚠️ There is no authentication. Anyone on the same LAN can read the shared folders. This is a tool for a trusted internal network only — not for exposing ports to the internet or hosting sensitive data.

---

How it works

Each PC is both a server and a client at the same time.

 [My PC]                                 [Coworker PC]
  share/  ──(served over HTTP)──►  ...  coworker pulls it → downloads/me/...
  downloads/coworker/...  ◄──(pulled periodically)──  coworker's share/

• Serves your share folder over a local port (default 8765) via HTTP
• Periodically pulls the shared folders of the peers listed in config.json, storing them under downloads/<peer-name>/<folder>/...
• Sync is a one-way pull: everyone serves their own share and only receives others'
• Transfers only changed files (compared by hash); files deleted at the source are removed on the receiver
• .fileshareignore (gitignore-style) excludes patterns from sharing (temp files, etc.)

---

Install

Windows — prebuilt binary (easiest, no Python needed)

A ready-to-run executable is published on the release branch: ⬇ Download FileShare.exe

1. Download FileShare.exe and put it in any folder (e.g. C:\Tools\FileShare\).
2. Double-click it. A tray icon appears, and on first run it auto-creates all the files/folders it needs right next to the exe (see What gets created on first run).
3. Edit the generated config.json to add your coworkers, save — done.

No Python, no pip install, no install.bat. Just the one file.

The binary lives on a dedicated release branch (not main) to keep the source history free of large build artifacts.

Windows — from source

1. Install Python 3 from python.org (check "Add Python to PATH" during install)
2. Double-click install.bat — installs dependencies (pystray, Pillow)
3. Run start.bat → an icon appears in the system tray

Linux / macOS

Requires Python 3 (run from source — no prebuilt binary is shipped for Linux).

./install.sh          # install dependencies
./start.sh            # run headless (daemon) in the foreground; Ctrl-C to stop

---

What gets created on first run

When you first launch FileShare (the exe or the script), it creates everything it needs next to the program, so nothing is scattered across your system:

Created item	Type	Role
config.json	file	Your settings: share folders, download location, port, sync interval, and the peer list. This is the one file you edit. Saving it reloads automatically — no restart.
.fileshareignore	file	Patterns (gitignore-style) excluded from sharing — temp files, __pycache__/, etc. Edit to add your own.
share/	folder	Your outbox. Put files here to share them with coworkers. (Configurable via share_folder.)
downloads/	folder	Your inbox. Coworkers' files land here under downloads/<peer-name>/<folder>/.... Mirrors the source — don't put working copies here.
logs/	folder	sync.log (sync activity, peer offline reasons) and access.log (who fetched what). First place to look when troubleshooting.
.fileshare_cache.json	file	Internal file-hash cache so unchanged files aren't re-transferred. Safe to delete (rebuilt automatically).

Tip: keep FileShare.exe in its own folder. Everything above lives beside it, so to move or back up your setup you just copy that one folder.

Usage

1) Configure (config.json)

A config.json is created automatically on first run. Fill in your coworkers' IPs and names.

{
  "share_folder": ["share"],          // folder(s) to share. A string or a list
  "download_folder": "downloads",     // where peers' files are received
  "port": 8765,                       // every PC must use the same port
  "sync_interval_seconds": 10,        // sync interval (seconds)
  "request_timeout_seconds": 5,
  "peers": [
    { "ip": "192.168.0.10", "name": "alice" },
    { "ip": "192.168.0.11", "name": "bob" }
  ]
}

• Relative paths are resolved against the program's location.
• Each share folder's basename must be unique (it's the identifier exposed to peers).
• Saving config.json takes effect without a restart.
• List files to exclude in .fileshareignore (gitignore format).

2) Run mode (auto-selected by OS)

OS	Default mode	Description
Windows	tray	Tray icon: check status / pause / sync now / open config / quit
Linux & others	headless	Runs as a background daemon with no UI

You can force a mode with flags:

python3 fileshare.py --headless   # daemon, no tray
python3 fileshare.py --tray       # tray UI (needs pystray/Pillow)

3) Controlling headless mode (Linux)

With no UI, you control it via signals and logs.

Action	How
Graceful shutdown	SIGTERM / Ctrl-C (systemctl stop)
Toggle share pause/resume	SIGUSR1
Sync now	SIGUSR2
Check status/logs	logs/sync.log, logs/access.log, or journalctl

---

Run as a service on Linux (systemd)

You can have it start automatically on boot/login and restart if it dies.

Per-user service

# After editing the two paths in fileshare.service to your install location:
mkdir -p ~/.config/systemd/user
cp fileshare.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now fileshare

systemctl --user status fileshare        # status
journalctl --user -u fileshare -f         # live logs

To keep it running after logout: sudo loginctl enable-linger "$USER"

System-wide service (server / NAS)

Copy fileshare.service to /etc/systemd/system/, set a dedicated account (User=/Group=) and absolute paths as described in the file's comments, then sudo systemctl enable --now fileshare.

See the comments at the top of fileshare.service for detailed install options.

---

Network / firewall

• All PCs must be on the same LAN and able to reach each other's IPs.
• The firewall must allow inbound TCP on port (default 8765).
  • Windows: click "Allow" on the firewall prompt at first launch
  • Linux: e.g. sudo ufw allow 8765/tcp
• If IPs change often, reserve static IPs (DHCP reservation) for the PCs on your router.

---

Files

File	Purpose
fileshare.py	The program source (server + sync + tray/headless)
config.json	Settings (peer list, port, folders). Auto-created on first run
.fileshareignore	Exclude patterns (gitignore format)
install.bat / start.bat	Windows install/run
install.sh / start.sh	Linux/macOS install/run
fileshare.service	Linux systemd unit (persistent service)
requirements.txt	Dependencies (pystray, Pillow — for tray mode)
logs/	Runtime logs (sync.log, access.log)

---

FAQ

Q. A coworker shows as offline. Likely the port is blocked by a firewall or the IP is wrong. The reason is logged in logs/sync.log.

Q. Is sync bidirectional? No. Each PC only uploads its own share and only receives others' — a one-way pull. When everyone runs a share, the net effect is mutual sharing.

Q. What if I edit a received file? Files under downloads/ mirror the source and are overwritten when the source updates. Keep your working copies in a share folder.

Q. Can it work over the internet? By design it's LAN-only. With no authentication, exposing it to the internet is not recommended.