Skip to main content

Web interface for directory listings and picture gallery

Project description

Simple web interface showing a directory-listing or thumbnail-gallery of the files or images in the files/ subdirectory. Users can upload files if the folder has write-permissions for all.

An example can be seen at

This repo is a python rewrite of the picbox php app.


You can quickly install the latest release and locally serve files from your ~/Pictures directory as follows:

pip install pycbox --user
pycbox -w ~/Pictures

In order to allow network access on all network interfaces you also need to add the --host option, e.g.:

pycbox -w ~/Pictures -h

Alternatively, you can run pycbox without installation from the git checkout. Though in this case, you still need to install the dependencies as follows:

pip install -r requirements.txt --user
./bin/pycbox -w ~/Pictures

However, running the pycbox from the command line like this is not recommended for deployment! From the flask documentation:

While lightweight and easy to use, Flask’s built-in server is not suitable for production as it doesn’t scale well and by default serves only one request at a time. Some of the options available for properly running Flask in production are documented here.

A more sophisticated server can e.g. be run using twisted:

twistd --nodaemon --logfile=- web --port=tcp:5000

In fact, the recommended method is using docker, see Deployment.


If it exists, config.yml will be loaded from the active directory. The config file may become mandatory, so you should always copy and adjust the shipped example config:

cp config.example.yml config.yml

An alternate config file name or path can be specified via the PYCBOX_CONFIG environment variable, i.e. like this:

PYCBOX_CONFIG=/path/to/alt_config.yml python
PYCBOX_CONFIG=/path/to/alt_config.yml twistd web


The recommended method is to run pycbox is via docker. The image can be built and run as follows:

docker build . -t pycbox
docker run --cap-drop=all \
    -v `pwd`/files:/pycbox/files \
    -p 5000:5000 \
    --name=pycbox pycbox

or simply:

docker-compose up

Add -d to either command line to run in the background.


In order to run the application on a subdomain, you will need to setup a proxy forward. Example nginx configuration to show the site on pix subdomain:

server {
    listen      80;
    listen [::]:80;
    return 301 https://$host$request_uri;

server {
    listen      443 ssl;
    listen [::]:443 ssl;
    access_log /var/log/nginx/access_pics.log;
    location / {
        proxy_pass                          http://localhost:5000;
        proxy_set_header X-Real-IP          $remote_addr;
        proxy_set_header Host               $host;
        proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade            $http_upgrade;
        proxy_set_header Connection         upgrade;


To enable uploading to a particular subfolder, make it writable by all:

mkdir -p files/public
chmod 777 files/public

Debug mode

DO NOT DO THIS IN PRODUCTION since it allows the client to execute arbitrary code.

To run the application in debug mode on port 5000, type either:

python --debug

or (recommended): FLASK_DEBUG=1 flask run

The second command takes care of reloading the server when the python module is changed and is therefore recommended for development.


  • use redis for caching thumbs and highlighted files

  • use asciidoc for markdown

  • use pygments for highlighting

  • configure via YAML file: auth, quota, uploads, deny globs



Date: 06.09.2017

  • fix startup error in debug mode, due to port being a string

  • fix startup error in docker container, due to permissions

  • fix error when trying to upload into root folder

  • fix permission problems in docker container


Date: 11.08.2017

  • fix install package (if installing using pip)


Date: 10.08.2017

Features include:

  • directory index

  • thumbnail gallery

  • highlighting (source-highlight or highlight)

  • cache thumbnails and highlights relative to current folder

  • configurable root folder

  • dockerfile

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pycbox-0.0.3.tar.gz (57.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page