KooZic uses Python 2.7, relies on PostgreSQL as a database system and FFmpeg for music transcoding. It uses as a core system the Odoo software.

KooZic is being extensively and exclusively tested on Ubuntu 16.04. However, it should work on any Linux distribution without much trouble. In case of problem, check the Odoo installation guide, as well as the FFmpeg documentation. Windows is not supported, while it should be possible to make it work on OSX.

A Docker image is available and provides an up and running installation without hassle. It should work on any Docker-supported platform (including Windows).

Automatic installation

An installation script is provided to automatize installation, un-installation and upgrade.


In a terminal, run the following:

curl >
chmod +x
sudo ./ install

Access KooZic in your browser at http://localhost:8069. The default login and password is “admin”. Change the password right away! Moreover, set a master password to secure the database at http://localhost:8069/web/database/manager.

Okay, now the details…

The installation script takes 2 optional arguments:

  • -u: user (default: root)
  • -d: install directory (default: /opt)

It is advised to use another user than root. Just make sure the user has access to the media folders.

The script will:

  • Retrieve the latest version
  • Install all the dependencies
  • Setup PostgreSQL
  • Install FFMpeg
  • Setup a systemd service

The following platforms are supported:

  • Ubuntu 16.04 (and derivatives, such as Linux Mint 17.x)
  • Debian 9 & 8
  • Fedora 27 (do not forget to check your SELinux configuration)
  • CentOS 7.4 (Python 3 must be installed)

Don’t like it?

sudo ./ uninstall

Note that PostgreSQL as well as the dependencies won’t be removed automatically (because I don’t want to screw your system). You might also want to remove FFMpeg at /usr/local/bin/ffmpeg.


After installing Docker, run the following command to download the latest KooZic image:

docker run -d -p 8069:8069 -p 8072:8072 -v <host_folder>:/mnt/host:ro --name koozic docmarty84/koozic

‘<host_folder>’ is the local folder containing your music.

KooZic should now be accessible in your browser at http://localhost:8069. To add your music in the library, simply create the folder ‘/mnt/host’ in the KooZic configuration.

The usual Docker instructions can be used to start and stop the container later on:

docker start koozic
docker stop koozic

The following instructions are outdated and kept for reference only. They were written when the installation script was not yet developed.

Initialize & Run KooZic

First, follow the instructions below corresponding to your distribution in order to install the dependencies.

Then, go in the directory where you downloaded KooZic. Note that the path cannot contain special characters (such as é, à, ç… For example, ‘/home/user/Téléchargement’ will lead to errors). Initialize the system:

./odoo-bin -i oomusic,oovideo -d koozic --without-demo=all --stop-after-init

Once the script has stopped, you are good to go! The server will run by default on port 8069 by running:


Access KooZic in your browser at http://localhost:8069. The default login and password is “admin”. Change the password right away! Moreover, set a master password to secure the database at http://localhost:8069/web/database/manager.

Dependencies on Debian & Ubuntu

On Ubuntu 16.04, everything is pretty much available out-of-the box.

Install the dependencies:

sudo apt install adduser node-less postgresql-client python python-dateutil python-decorator\
    python-docutils python-feedparser python-imaging python-jinja2 python-ldap python-libxslt1\
    python-lxml python-mako python-mock python-openid python-passlib python-psutil python-psycopg2\
    python-pybabel python-pychart python-pydot python-pyparsing python-pypdf python-reportlab\
    python-requests python-suds python-tz python-vatnumber python-vobject python-werkzeug\
    python-xlsxwriter python-xlwt python-yaml postgresql python-mutagen ffmpeg mediainfo

On Ubuntu 14.04, FFmpeg is available in this PPA. On Debian 8.5, it is available in the backports.

Create the user in PostgreSQL. It should be the same user than the one you will use to run KooZic:

sudo su - postgres -c "createuser -s <your_user>"


If you are facing issues with the scan of your library (e.g. missing songs), we suggest to install Pytaglib. It should accept more easily incorrect music files.

sudo apt install python-dev libtag1-dev python-pip

Install the package pytaglib thanks to pip, since it is not available in the repositories for Python 2:

sudo pip install pytaglib==1.4.1

Dependencies on Fedora

KooZic has been tested on Fedora 25.

ffmpeg should first be installed. It is available in the rpmfusion repositories.

Install the dependencies:

dnf install babel libxslt-python nodejs-less pychart pyparsing python-babel python-dateutil\
   python-decorator python-docutils python-feedparser python-imaging python-jinja2 python-ldap\
   python-lxml python-mako python-mock python-openid python-passlib python-psutil python-psycopg2\
   python-reportlab python-requests python-vobject python-werkzeug python-xlwt python-yaml pytz\
   postgresql postgresql-server postgresql-libs postgresql-contrib postgresql-devel python-mutagen mediainfo

Install extra dependencies thanks to easy_install:

easy_install pyPdf vatnumber pydot suds ofxparse XlsxWriter

Configure PostgreSql:

mkdir -p /var/lib/postgres/data
chown -R postgres:postgres /var/lib/postgres/data

As postgres user:

su - postgres
initdb -D /var/lib/postgres/data -E UTF-8
pg_ctl -D /var/lib/postgres/data -l logfile start
createuser -s <your_user>

Additional info

If you are still facing issues to install the dependencies, you might have a look at the package files. They will give you some clues on how dependencies can be installed.