Simple web file browser using flask





GitHub Stars



Last Commit

2mos ago











.. image:: :target: :alt: Travis-CI badge

.. image:: :target: :alt: AppVeyor badge

.. image:: :target: :alt: Coveralls badge

.. image:: :target: :alt: Codacy badge

.. image:: :target: :alt: License: MIT

.. image:: :target: :alt: Version: 0.5.6

.. image:: :target: :alt: Python 2.7+, 3.3+

The simple web file browser.


Head to for an online version of current master documentation,

You can also build yourself from sphinx sources using the documentation Makefile located at docs directory.


.. image:: :target: :alt: Screenshot of directory with enabled remove


  • Simple, like Python's SimpleHTTPServer or Apache's Directory Listing.
  • Downloadable directories, streaming directory tarballs on the fly.
  • Optional remove for files under given path.
  • Optional upload for directories under given path.
  • Player audio player plugin is provided (without transcoding).

New in 0.5

  • File and plugin APIs have been fully reworked making them more complete and extensible, so they can be considered stable now. As a side-effect backward compatibility on some edge cases could be broken (please fill an issue if your code is affected).

    • Old widget API have been deprecated and warnings will be shown if used.
    • Widget registration in a single call (passing a widget instances is still available though), no more action-widget duality.
    • Callable-based widget filtering (no longer limited to mimetypes).
    • A raw HTML widget for maximum flexibility.
  • Plugins can register command-line arguments now.

  • Player plugin is now able to load m3u and pls playlists, and optionally play everything on a directory (adding a command-line argument).

  • Browsing now takes full advantage of scandir (already in Python 3.5 and an external dependency for older versions) providing faster directory listing.

  • Custom file ordering while browsing directories.

  • Easy multi-file uploads.

  • Jinja2 template output minification, saving those precious bytes.

  • Setup script now registers a proper browsepy command.


It's on pypi so...

.. _pypi:

.. code-block:: bash

pip install browsepy

You can get the development version from our github repository.

.. _github repository:

.. code-block:: bash

pip install git+


Serving $HOME/shared to all addresses

.. code-block:: bash

browsepy 8080 --directory $HOME/shared

Showing help

.. code-block:: bash

browsepy --help

Showing help including player plugin arguments

.. code-block:: bash

browsepy --plugin=player --help

This examples assume python's bin directory is in PATH, otherwise try replacing browsepy with python -m browsepy.

Command-line arguments

This is what is printed when you run browsepy --help, keep in mind that plugins (loaded with plugin argument) could add extra arguments to this list.


usage: browsepy [-h][--directory PATH] [--initial PATH][--removable PATH] [--upload PATH][--exclude PATTERN] [--exclude-from PATH][--plugin MODULE] [host][port]

positional arguments: host address to listen (default: port port to listen (default: 8080)

optional arguments: -h, --help show this help message and exit --directory PATH serving directory (default: current path) --initial PATH default directory (default: same as --directory) --removable PATH base directory allowing remove (default: none) --upload PATH base directory allowing upload (default: none) --exclude PATTERN exclude paths by pattern (multiple) --exclude-from PATH exclude paths by pattern file (multiple) --plugin MODULE load plugin module (multiple)

Using as library

It's a python module, so you can import browsepy, mount app, and serve it (it's WSGI_ compliant) using your preferred server.

Browsepy is a Flask application, so it can be served along with any WSGI_ app just setting APPLICATION_ROOT in config to browsepy prefix url, and mounting on the appropriate parent url-resolver/router.

.. _WSGI:

Browsepy app config (available at uses the following configuration options.

  • directory_base: anything under this directory will be served, defaults to current path.
  • directory_start: directory will be served when accessing root URL
  • directory_remove: file removing will be available under this path, defaults to None.
  • directory_upload: file upload will be available under this path, defaults to None.
  • directory_tar_buffsize, directory tar streaming buffer size, defaults to 262144 and must be multiple of 512.
  • directory_downloadable whether enable directory download or not, defaults to True.
  • use_binary_multiples whether use binary units (bi-bytes, like KiB) instead of common ones (bytes, like KB), defaults to True.
  • plugin_modules list of module names (absolute or relative to plugin_namespaces) will be loaded.
  • plugin_namespaces prefixes for module names listed at plugin_modules where relative plugin_modules are searched.
  • exclude_fnc function will be used to exclude files from listing and directory tarballs. Can be either None or function receiving an absolute path and returning a boolean.

After editing plugin_modules value, plugin manager (available at module plugin_manager and app.extensions['plugin_manager']) should be reloaded using the reload method.

The other way of loading a plugin programmatically is calling plugin manager's load_plugin method.

Extend via plugin API

Starting from version 0.4.0, browsepy is extensible via plugins. A functional 'player' plugin is provided as example, and some more are planned.

Plugins can add HTML content to browsepy's browsing view, using some convenience abstraction for already used elements like external stylesheet and javascript tags, links, buttons and file upload.

More information at

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0