localfs

A simple, fast, and beautiful local file sharing service built with Python and Flask. Share your media library (videos, audio, images) across your local network through a clean, modern web interface.

Features

• Instant web access — view and download files from any device on your network
• Built-in video & audio player with auto-generated thumbnails
• Live search filtering
• Clean, modern UI styled with Tailwind CSS
• Configurable file-type filtering
• Optional access key for web interface security
• JSON API endpoint for sharing activity logs

Quick Start

Install via pip

pip install localfs

Install from source

git clone https://github.com/rkriad585/localfs.git
cd localfs
pip install -e .
python -m localfs

Install via script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/rkriad585/localfs/main/installer.sh | sh

Install via script (Windows PowerShell)

irm https://raw.githubusercontent.com/rkriad585/localfs/main/installer.ps1 | iex

Open the URL printed in the terminal to access the web interface.

Docker

docker build -t localfs .
docker run -p 5000:5000 -v ./media:/app/media localfs

Or with docker compose:

docker compose up

Documentation

Full documentation is in the docs/ directory:

Build Commands

make build      # Build wheel and sdist
make install    # Install in editable mode
make test       # Run tests
make lint       # Run linter
make format     # Format code
make run        # Start server
make clean      # Remove build artifacts
make docker     # Build Docker image

Project Structure

localfs/
├── main.py              # Application entry point and Flask routes
├── config.py            # Configuration constants
├── pyproject.toml       # Project metadata and dependencies
├── Dockerfile           # Multi-stage Docker build
├── docker-compose.yml   # Docker Compose configuration
├── Makefile             # Build automation
├── build.sh / .ps1      # Cross-platform build scripts
├── installer.sh / .ps1  # System installer / uninstaller
│
├── data/                # Runtime data (logs, auto-created)
├── media/               # Place your shared files here
├── static/
│   ├── js/main.js       # Search filtering logic
│   ├── logo.svg         # Project logo
│   └── thumbnails/      # Auto-generated video thumbnails
├── templates/
│   ├── index.html       # File grid homepage
│   ├── player.html      # Video/audio player page
│   └── error.html       # Error pages (401/403/404/500)
├── tests/
│   ├── conftest.py      # Pytest fixtures
│   ├── test_config.py   # Config tests
│   └── test_main.py     # Main application tests
└── docs/                # Documentation

Uninstalling

localfs --selfuninstall

Uninstall via script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/rkriad585/localfs/main/installer.sh | sh -s -- --selfuninstall

Uninstall via script (Windows PowerShell)

Invoke-RestMethod -Uri "https://raw.githubusercontent.com/rkriad585/localfs/main/installer.ps1" | Invoke-Expression -ArgumentList "--selfuninstall"

License

Distributed under the MIT License. See LICENSE for more information.