HomeGallery is a command line tool to init the configuration, start the web server at localhost:3000 and import the media sources. To run your gallery at home you need to

  • install the software

  • initialize the configuration

  • run the local web server

  • import your media sources

HomeGallery can run through

  • prebuilt binary on Linux, Mac on Windows

  • as docker container

  • docker-compose

  • application bundle Linux, Mac on Windows

  • from source

Installation Tutorial

Prebuilt binaries

Download the binary for your platform:

Other download options can be found here. and there are also unstable releases from the current development stage.

A prebuilt binary is a command line application through a selfextracting archive. On the first start it extracts all required files to a temporary directory and starts the gallery CLI. Please be patient on the first start. Future starts skip the extraction and the gallery starts faster.

The gallery CLI requires a gallery.config.yml configuration file and it is created if missing. See Configuration section for details and comments.

By default the HomeGallery stores the configuration files in ~/.config/home-gallery. The generated preview and extracted meta data files are stored in ~/.cache/home-gallery/storage. For docker containers theses directories are different.


On Windows the app might be blocked by the anti virus application and should be allowed manually.


On Mac the app might be blocked the OS and should be allowed manually. See Open a Mac app from an unidentified developer.


1curl -sL -o gallery
2chmod 755 gallery
3./gallery init --source ~/Pictures
4./gallery run server &
5./gallery run import --initial

While your media files are imported open your HomeGallery at localhost:3000 in your browser.


HomeGallery offers docker image at xemle/home-gallery (amd64 and arm64 architecture). These image are build via GitHub actions.

Data volume structure

The gallery application is located at /app whereas the data is stored in /data within the container. The /data folder has following structure:

`-- /data - Docker data volume
  +-- sources - Your media file sources or other volumne mounts
  +-- config - File index, database and configuration files
  | `-- gallery.config.yml - Main configuration file
  `-- storage - Preview images and meta data

The media volumes should be mounted into the /data directory. Eg. mount your host directory ~/Pictures to /data/Pictures in the container and add it as source to your gallery.config.yml.

To avoid user permission problems it is advisable to run the container with your user and group id via -u parameter.


1mkdir -p data
2alias gallery="docker run -ti --rm \
3  -v $(pwd)/data:/data \
4  -v $HOME/Pictures:/data/Pictures \
5  -u $(id -u):$(id -g) \
6  -p 3000:3000 xemle/home-gallery"
7gallery init --source /data/Pictures
8gallery run server &
9gallery run import --initial

While your media files are imported open your HomeGallery at localhost:3000 in your browser.

Custom image

You can customize and build the docker image by your own

git checkout
cd home-gallery
docker build -t home-gallery .

Docker Compose

Docker compose simplifies the configuration of containers and connected services. Following example starts the HomeGallery with a local api server.

 1version: "3.9"
 3  api:
 4    # custom build via
 5    #build: packages/api-server
 6    image: xemle/home-gallery-api-server
 7    environment:
 8      # TensorflowJS backends: cpu, wasm and node. Use wasm
 9      # if you have troubles.
10      #- BACKEND=cpu
11      #- BACKEND=wasm
12      - BACKEND=node
13    ports:
14      - "3000"
15  gallery:
16    # custom build via
17    #build: .
18    image: xemle/home-gallery
19    environment:
20      - GALLERY_API_SERVER=http://api:3000
21      - GALLERY_OPEN_BROWSER=false
22    volumes:
23      - ./data:/data
24      # Mount your media directories below /data
25      - ${HOME}/Pictures:/data/Pictures
26    expose:
27      - "3000:3000"
28    user: "${CURRENT_USER}"
29    entrypoint: ['node', '/app/gallery.js', 'run', 'server']


The example uses node backend in the API server which is only supported for amd64 hosts. Use BACKEND=wasm on Raspberry PIs or if you discover troubles.


1mkdir -p data
2echo "CURRENT_USER=$(id -u):$(id -g)" >> .env
3docker-compose exec gallery /app/gallery.js run init --source /data/Pictures
4docker-compose up
5docker-compose exec gallery /app/gallery.js run import --update

Application bundle

HomeGallery can be also downloaded as tar.gz archive from for Linux, Mac and Windows. These tar.gz archives are the same as the prebuilt binaries. You have to start the main script manually.

Source code

If you like to fix and tweak HomeGallery you can checkout the source code, install the npm dependencies and build the packages.


1git checkout
2cd home-gallery
3npm install
4npm run build
5./gallery.js run init --source ~/Pictures
6./gallery.js run server &
7./gallery.js run import --initial