Welcome to installation guide! This guide describes how to install on various platforms. Please read and follow the instructions carefully to ensure your installation is functional and smooth.

The preferred installation is to Run with Docker as this is the simplest to setup and get started. Running with Docker guarantee the availability of all features with the minimum configuration required. This installation works across all Operating Systems.

Alternatively, you can install locally as a development server with some limitations and caveats. Refer to the Local development installation section.

Run with Docker

Get Docker

The first step is to download and install Docker on your platform. Refer to Docker documentation and choose the best installation path for your system: Get Docker.

Build the Image is distributed with Dockerfile and docker-compose.yml files required for the creation of the Docker image.


On Windows, ensure that git autocrlf configuration is set to false before cloning the repository:

git config --global core.autocrlf false

Clone the git repo, create an environment file, and build the Docker image:

git clone && cd
make envfile
docker compose build


As the docker-compose v1 command is officially deprecated by Docker, you will only find references to the docker compose v2 command in this documentation.

Run the App

Run your image as a container:

docker compose up

At this point, the app should be running at port 80 on your Docker host. Go to http://localhost/ on a web browser to access the web UI.

An overview of the web application usage is available at User Interface.


Congratulations, you are now ready to use, and you can move onto the Tutorials section starting with the Analyze Docker Image (Web UI) tutorial.

Tip will take advantage of all the CPUs made available by your Docker configuration for faster processing.

Make sure to allow enough memory to support each CPU processes.

A good rule of thumb is to allow 2 GB of memory per CPU. For example, if Docker is configured for 8 CPUs, a minimum of 16 GB of memory is required.


By default, starts only 1 worker, which means only 1 pipeline will be executed at a time. If you wish to start more workers, use the following command, replacing the number 2 with the desired number of workers:

docker compose up --scale worker=2


To access a dockerized app from a remote location, the ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS settings need to be provided in your .env file, for example:

Refer to ALLOWED_HOSTS settings and CSRF_TRUSTED_ORIGINS settings for more details.


If you run on desktop or laptop, it may come handy to pause/unpause or suspend your local system. For this, use these commands:

docker compose pause  # to pause/suspend
docker compose unpause  # to unpause/resume

Upgrade the App

Update your local repo, and build the Docker image:

git pull
docker compose build


The Docker image has been updated to run as a non-root user. If you encounter “permissions” issues while running the Docker images following the docker compose build, you will need to update the the permissions of the /var/scancodeio/ directory of the Docker volumes using:

docker compose run -u 0:0 web chown -R app:app /var/scancodeio/

See also


You need to rebuild the image whenever’s source code has been modified or updated.

Execute a Command


Refer to the Command Line Interface section for the full list of commands.

A scanpipe command can be executed through the docker compose command line interface with:

docker compose exec -it web scanpipe COMMAND

Use alternative HTTP ports

By default, the application is accessible on port 80 for HTTP and 443 for HTTPS requests. This assumes that these ports are not already occupied by another application. You can customize both of these ports by adjusting the following variables in the .env file, located in the root of the application directory, next to the docker-compose.yml file:


Offline installation with Docker can be installed and operated on a server that is not connected to the internet, such as an “airgapped” or isolated server.

To achieve this, Docker images are initially built on a machine with internet access and subsequently transferred to the “offline” server for isolated installation.


docker and docker compose are required on both the local machine and the server.

Build the offline installation package

Build and save the offline installation package with docker images, configuration and scripts on your local machine:

make offline-package

A tarball scancodeio-offline-package-VERSION.tar will be created in the dist/ directory.

Install on an offline server

Copy the tarball to the server then extract it replacing VERSION with the actual version value:

tar -xf scancodeio-offline-package-VERSION.tar

Change to the extracted build/ directory:

cd build

Load the docker Images:

docker load --input scancodeio-images.tar.gz

Run on an offline server

Run the App by starting the services:

docker compose --file docker-compose-offline.yml up

And visit the web UI at: http://localhost/project/


The nginx service (webserver) requires the port 80 to be available on the host. In case the port 80 is already in used, you will encounter the following error:

ERROR: for build_nginx_1 Cannot start service nginx: driver failed programming ...

You can attempt to stop potential running services blocking the port 80 with the following commands on the host before starting services:

sudo systemctl stop nginx
sudo systemctl stop apache2

Local development installation

Supported Platforms has been tested and is supported on the following operating systems:

  1. Debian-based Linux distributions

  2. macOS 10.14 and up


On Windows can only be Run with Docker.

Pre-installation Checklist

Before you install, make sure you have the following prerequisites:

System Dependencies

In addition to the above pre-installation checklist, there might be some OS-specific system packages that need to be installed before installing

On Linux, several system packages are required by the ScanCode toolkit. Make sure those are installed before attempting the installation:

sudo apt-get install \
    build-essential python3-dev libssl-dev libpq-dev \
    bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev libpopt0 \
    libgpgme11 libdevmapper1.02.1 libguestfs-tools

See also ScanCode-toolkit Prerequisites for more details.

For the Collect symbols with Ctags (addon) pipeline, Universal Ctags is needed.

  • On Linux install it using:

    sudo apt-get install universal-ctags
  • On MacOS install Universal Ctags using Homebrew:

    brew install universal-ctags

For the Collect string with Xgettext (addon) pipeline, gettext is needed.

  • On Linux install it using:

    sudo apt-get install gettext
  • On MacOS install gettext using Homebrew:

    brew install gettext

Clone and Configure

  • Clone the GitHub repository:

    git clone && cd
  • Inside the directory, install the required dependencies:

    make dev


You can specify the Python version during the make dev step using the following command:

make dev PYTHON_EXE=python3.11

When PYTHON_EXE is not specified, by default, the python3 executable is used.


When running M1 based MacOS, you can also install SCIO in x86 mode using rosetta:

softwareupdate --install-rosetta
arch -x86_64 /bin/bash -c "$(curl -fsSL"
arch -x86_64 /usr/local/Homebrew/bin/brew install python@3.12
make dev PYTHON_EXE=/usr/local/bin/python3.12
(. bin/activate; pip install psycopg[binary])
  • Create an environment file:

    make envfile


PostgreSQL is the preferred database backend and should always be used on production servers.

  • Create the PostgreSQL user, database, and table with:

    make postgresdb


The make postgres command is assuming that your PostgreSQL database template is using the en_US.UTF-8 collation. If you encounter database creation errors while running this command, it is generally related to an incompatible database template.

You can either update your template to fit the default, or provide custom values collation using the POSTGRES_INITDB_ARGS variable such as:

make postgresdb POSTGRES_INITDB_ARGS=\
    --encoding=UTF-8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8


You can also use a SQLite database for local development as a single user with:

make sqlitedb


Choosing SQLite over PostgreSQL has some caveats. Check this link for more details.


You can validate your installation by running the tests suite:

make test

Web Application

A web application is available to create and manage your projects from a browser; you can start the local webserver and access the app with:

make run

Then open your web browser and visit: http://localhost:8001/ to access the web application.


make run is provided as a simplified way to run the application with one major caveat: pipeline runs will be executed synchronously on HTTP requests and will leave your browser connection or API calls opened during the pipeline execution. See also the SCANCODEIO_ASYNC setting.


This setup is not suitable for deployments and only supported for local development. It is highly recommended to use the Run with Docker setup to ensure the availability of all the features and the benefits from asynchronous workers for pipeline executions.

An overview of the web application usage is available at User Interface.


If you already have the repo cloned, you can upgrade to the latest version with:

git pull
make dev
make migrate

Helm Chart [Beta]


The Helm Chart support for is a community contribution effort. It is only tested on a few configurations and still under development. We welcome improvement suggestions and issue reports at GitHub repo.


Helm must be installed to use the charts. Please refer to Helm’s documentation to get started.


  • Kubernetes cluster running with appropriate permissions (depending on your cluster)

  • kubectl set up to connect to the cluster

  • helm

Tested on:

  • minikube v1.25.1:

    $ minikube version
    minikube version: v1.25.1
    commit: 3e64b11ed75e56e4898ea85f96b2e4af0301f43d
  • helm v3.8.1:

    $ helm version
    GitTreeState:"clean", GoVersion:"go1.17.5"}


Once Helm is properly set up, add the scancode-kube repo as follows:

# clone github repository
git clone

# create kubernetes namespace
kubectl create namespace scancode

# configure values.yaml file
vi values.yaml

# install helm dependencies
helm dependency update

# check if dependencies are installed
helm dependency list

# sample output
# NAME            VERSION REPOSITORY                              STATUS
# nginx           9.x.x      ok
# postgresql      11.x.x      ok
# redis           16.x.x      ok

# install scancode helm charts
helm install scancode ./ --namespace scancode

# wait until all pods are in Running state
# afterwards cancel this command as it will run forever
kubectl get pods -n scancode --watch

# sample output
# NAME                                       READY   STATUS    RESTARTS   AGE
# scancode-nginx-f4d79f44d-4vhlv             1/1     Running   0          5m28s
# scancode-postgresql-0                      1/1     Running   0          5m28s
# scancode-redis-master-0                    1/1     Running   0          5m28s
# scancode-scancodeio-web-5786df657c-khrgb   1/1     Running   0          5m28s
# scancode-scancodeio-worker-0               1/1     Running   1          5m28s

# expose nginx frontend
minikube service --url=true -n scancode scancode-nginx



The Gitpod support for is a community contribution effort. We welcome improvement suggestions and issue reports at GitHub repo.


  • Create a new Workspace and open it in VSCode Browser or your preferred IDE. Provide the GitHub repo URL:

  • Open the “TERMINAL” window and create the .env file with:

    make envfile
  • Open the generated .env file and add the following settings:

Run the App

  • Build and run the app container:

    docker compose build
    docker compose up

At this stage, the app is up and running. To access the app, open the “PORTS” window and open the address for port 80 in your browser.