python-livereload

python-livereload is a Python library and command-line tool that reloads web pages in the browser automatically whenever watched files change, so web developers no longer need to hit refresh manually. It runs a small web server that injects a LiveReload client script and pushes reload events over a WebSocket when files are updated.

Beyond the standalone CLI, it exposes a scriptable Server API that lets you register watch paths, attach shell or Python callbacks to run on change (such as recompiling assets), and serve a directory. This makes it a common building block for documentation and static-site build workflows in the Python ecosystem.

What You Get

• A live-reloading development web server that pushes browser refreshes over WebSocket
• A scriptable Server API to watch file globs and run shell or Python callbacks on change
• A livereload command-line tool for zero-code directory serving
• Integration hooks used by documentation and static-site build tooling

Common Use Cases

• Auto-refreshing a browser while editing HTML, CSS, and JavaScript
• Rebuilding documentation or assets on save and reloading the preview
• Serving a static site locally with instant reload during development

Under The Hood

Architecture - The core is livereload/server.py, which builds a Tornado-based web application: handlers.py serves files and hosts the LiveReload WebSocket endpoint that injects and talks to the browser client, while watcher.py polls the filesystem for changes and triggers reloads (optionally running registered shell/Python tasks first). cli.py and __main__.py provide the livereload command, and vendored client assets live under livereload/vendors.

Tech Stack - It is pure Python built on the Tornado async web framework and IOLoop for serving and WebSocket handling, packaged via setup.py/setup.cfg. A filesystem watcher drives the change-detection loop, and a bundled JavaScript LiveReload client handles the in-browser reload.

Code Quality - The repository ships a tests/ suite covering the server and watcher (test_server.py, test_watcher.py), a Makefile for tasks, example projects, and Read the Docs documentation. The project is mature and stable, with lower recent activity but a long track record.

API Design - The programmatic API is concise and ergonomic: instantiate Server(app), call server.watch('path/glob', optional_callback) to register triggers, and server.serve() to start serving with live reload. The CLI covers the no-code case, so users can start with a single command and graduate to the scriptable API for build integration.