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:
| Guide | Description |
|---|---|
| Setup Guide | Installation and first run |
| Usage Guide | How to use localfs |
| Configuration | All config options explained |
| API Reference | JSON API documentation |
| Development | Setting up a dev environment |
| Deployment | Production deployment options |
| Troubleshooting | Common issues and fixes |
| Architecture | Project architecture overview |
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.
Metadata
Release files for localfs 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| localfs-1.0.0.tar.gz | 34.7 kB | Without provenance | Details for localfs-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| localfs-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for localfs-1.0.0-py3-none-any.whl |
Total release size: 54.2 kB
Release files / localfs-1.0.0.tar.gz
| Download URL | localfs-1.0.0.tar.gz |
|---|---|
| Size | 34.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c92c23b723fd77ebc4d4a0e4ae136484e2b930bbddbe6feaa2f82a87cf5f33f2
|
|
BLAKE2b-256 checksum How to use checksums |
678ed6afbc4dbdcef87358b26f97d4ee2a8d48c665b2ac0fed83db04fe287538
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Release files / localfs-1.0.0-py3-none-any.whl
| Download URL | localfs-1.0.0-py3-none-any.whl |
|---|---|
| Size | 19.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
da31d7637318f514ddc6d672f6fbff1f916f560dde19bb789931b14231674eff
|
|
BLAKE2b-256 checksum How to use checksums |
d5955a7acce495c8c0c508547938d74ef1de2d046a47ae155f72dac8e5bdaf96
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.4
|
Security for localfs 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.