Comprehensive Installation

The recommended way to install ScanCode is using app archives:

  • Installation as an Application: Downloading Releases

    The recommended method is to download the latest application release as anapplication and then configure and use directly. No knowledge of pip/git orother developer tools is necessary. You only need to install Python thendownload and extract the ScanCode application archive to run ScanCode.For standard usage that’s all you need.

For advanced usage and experienced users, you can also use any of these mode:

  • Installation via Docker:

    An alternative to installing the latest ScanCode-Toolkit release natively isto build a Docker image from the included Dockerfile. The only prerequisiteis a working Docker installation.

  • Installation from Source Code: Git Clone

    You can clone the git source code repository and then run the configure scriptto configure and install ScanCode for local and development usage.

  • Installation as a library: via pip

    To use ScanCode as a library in your application, you can install it viapip. This is recommended for developers or users familiar with Pythonthat want to embed ScanCode as a library.

  • Install from Fedora’s repository

    ScanCode is part of main Fedora Linux repository. It will automatically installall dependencies. This is recommended for production deployments.

Before Installing

  • ScanCode requires a Python version between 3.10 to 3.13 and istested on Linux, macOS, and Windows. It should work fine on FreeBSD.

System Requirements

  • Hardware : ScanCode will run best with a modern X86 64 bits processor and atleast 8GB of RAM and 2GB of disk space. These are minimum requirements.

  • Supported operating systems: ScanCode should run on these 64-bit OSes runningX86_64 processors:

    1. Linux: on recent 64-bit Linux distributions,

    2. Mac: on recent x86 64-bit macOS (10.15 and up, including 11 and 12),Use the X86 emulation mode on Apple ARM M1 CPUs.(Note thatpip install does not work on ARM CPUs)

    3. Windows: on Windows 10 and up,

    4. FreeBSD.

Prerequisites

ScanCode needs a Python 3.10+ interpreter; We support all Python versions from3.10 to 3.12. The default version for the application archives is Python 3.10

  • On Linux:

    Use your package manager to installpython3.

    For Ubuntu, it issudoaptinstallpython3-dev

    • On Ubuntu 16, 18, 20 ,22 and 24 run:

      sudoaptinstallpython-devbzip2xz-utilszlib1glibxml2-devlibxslt1-devlibpopt0

    • On Debian and Debian-based distros run:

      sudoapt-getinstallpython3-devlibbz2-1.0xz-utilszlib1glibxml2-devlibxslt1-devlibpopt0

    • On RPM-based distros run:

      sudoyuminstallpython3.10-develzlibbzip2-libsxz-libslibxml2-devellibxslt-devellibpopt0

    • On Fedora 22 and later run:

      sudodnfinstallpython3.10-develxz-libszliblibxml2-devellibxslt-develbzip2-libslibpopt0

    If these packages are not available from your package manager, you mustcompile them from sources.

  • On Mac:

    The default Python 3 provided with macOS is 3.10.Alternatively you can download and install Python 3.10 fromhttps://www.python.org/

  • On Windows:

    Download and install Python 3.10 fromhttps://www.python.org/

    Note

    64-bit Python interpreters (x86-64) are the only interpreters supported byScanCode on all operating systems which means only 64-bit Windows is supported.

    See theInstallation on Windows 10/11 section for more installation details.

Installation as an Application: Downloading Releases

Get the ScanCode-Toolkit tarball archive of a specific version and youroperating system by going to theproject releases page

For example, Version 30.0.1 archive can be obtained fromToolkit release 30.0.1under assets options.

Note

ScanCode app archives come with packaged with all required dependencies exceptfor Python that has to be downloaded and installed separately.On more recent versions of Ubuntu, you will have to install Python 3.10 manually.One possibility is to use the Deadsnakes PPA (Personal Package Archive) which isa project that provides older Python version builds for Debian and Ubuntu and isavailable athttps://github.com/deadsnakes/ andhttps://launchpad.net/~deadsnakes/+archive/ubuntu/ppa

sudoapt-getupdate&&sudoapt-getupgradesudoadd-apt-repositoryppa:deadsnakes/ppa--yessudoapt-getinstallpython3.10python3.10-distutils

Installation on Linux and Mac

Download the archive for your operating systen and extractthe archive from command line:

tar-xvfscancode-toolkit-30.0.1_py38-linux.tar.gz

Or, on Linux, right click and select “Extract Here”.

Check whether thePrerequisites are installed. Open a terminalin the extracted directory and run:

./scancode--help

This will configure ScanCode and display the command lineHelp text.

Note

If you encounter a “No matching distribution” error while running the./configure command on a Mac M1, it may indicate compatibility issues with the current architecture. Here’s a step-by-step guide to address this:

  • Change Mac M1 Architecture to x86_64:Switch the architecture from amd64 to x86_64 using the command:

    env/usr/bin/arch-x86_64/bin/zsh--login

  • Use Rosetta Translation:Enable Rosetta translation in Terminal by executing:

    softwareupdate--install-rosetta

  • Transition Homebrew from arm64 to Intel:Change Homebrew from the arm64 architecture to the Intel (x86) architecture by running:

    /bin/bash-c"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

  • Install Intel-Specific Python:Use Homebrew to install Python specifically optimized for Intel architecture with:

    /usr/local/Homebrew/bin/brewinstallpython3

Then rerun the./configure command. This sets up the project according to the new architecture and ensures proper configuration.Following these steps should help resolve compatibility issues and allow smooth operation of the project on Mac M1 devices.

Installation on Windows 10/11

  • Download the latest ScanCode release zip file for Windows from the latestversion athttps://github.com/aboutcode-org/scancode-toolkit/releases/

  • In the File Explorer, select the downloaded ScanCode zip and right-click.

  • In the pop-up menu select ‘Extract All…’

  • In the pop-up window ‘Extract Compressed (Zipped) Folders’ use the default options to extract.

  • Once the extraction is complete, a new File Explorer window will pop up.

  • In this Explorer window, select the new folder that was created and right-click.

Note

On Windows, double-click the new folder, select one of the files inside the folder(e.g., ‘setup.py’), and right-click.

  • In the pop-up menu select ‘Properties’.

  • In the pop-up window ‘Properties’, select the Location value. Copy this to the clipboard andclose the ‘Properties’ window.

  • Press the start menu button, click the search box or search icon in the taskbar.

  • In the search box type:

    cmd

  • Select ‘cmd.exe’ or ‘Command Prompt’ listed in the search results.

  • A new ‘Command Prompt’pops up.

  • In this window (aka a ‘command prompt’), type ‘cd’ followed by a space andthen Right-click in this window and select Paste. This will paste the path youcopied before and is where you extracted ScanCode:

    cdpath\to\extracted\ScanCode

  • Press Enter.

  • This will change the current location of your command prompt to the root directory whereScanCode is installed.

  • Then type:

    scancode-h

  • Press enter. This first command will configure your ScanCode installation.Several messages are displayed followed by the ScanCode command help.

  • The installation is complete.

Un-installation

  • Delete the directory in which you extracted ScanCode.

  • Delete any temporary files created in your system temp and user temp directoryunder a ScanCode-prefixed directory such as .scancode-tk or .cache/scancode-tk.

Note

The above installation process can be used withCommand Promptcmd, andPowerShell.Git Bash is not tested and using it mayintroduce unexpected behavior. If you’re usingWindows Subsystem forLinuxWSL2, please refer toInstallation on Linux and Mac sectionabove.

Installation via Docker:

You can install ScanCode-Toolkit by building a Docker image from the included Dockerfile.The prerequisite is a workingdocker installation.

Download the ScanCode-Toolkit Source Code

Run the following once you haveGit installed:

gitclonehttps://github.com/aboutcode-org/scancode-toolkit.git

Build the Docker image

Run thedockerbuild source code checkout directory.:

cd scancode-toolkitdocker build --tag scancode-toolkit --tag scancode-toolkit:$(git describe --tags) .

Note

As$(gitdescribe--tags) is a Unix-style command. If you are onwindows, please run thegitdescribe--tags separately to get theoutput, then manually insert that value into your Docker command.For instance,

C:\scancode-toolkit>gitdescribe--tagsv32.4.1C:\scancode-toolkit>dockerbuild--tagscancode-toolkit--tagscancode-toolkit:v32.4.1.

Run using Docker

The docker image will forward all arguments it receives directly to thescancode command.

Display help:

dockerrunscancode-toolkit--help

Mount current working directory as “/project” and run a scan on a file nameapache-2.0.LICENSE directory. The JSON results will be in scan-result.json:

docker run -v $PWD/:/project scancode-toolkit -clipeu --json-pp /project/scan-result.json /project/apache-2.0.LICENSE

This will mount your current working from the host into/project in the containerand then scan the contents. The outputresult.json will be written back to yourcurrent working directory on the host.

Note that the parametersbeforescancode-toolkit are used for docker,those after will be forwarded to scancode.

Installation from Source Code: Git Clone

You can download the ScanCode-Toolkit Source Code and build from it yourself.This is what you would want to do it if:

  • You are developing ScanCode or adding new patches or want to run tests.

  • You want to test or run a specific version/checkpoint/branch from the version control.

Download the ScanCode-Toolkit Source Code

Run the following once you haveGit installed:

gitclonehttps://github.com/aboutcode-org/scancode-toolkit.gitcdscancode-toolkit

Configure the build

ScanCode use a configure scripts to create an isolated virtual environment,install required packaged dependencies.

On Linux/Mac:

  • Open a terminal

  • cd to the clone directory

  • run./configure

  • runsourcevenv/bin/activate

On Windows:

  • open a command prompt

  • cd to the clone directory

  • runconfigure

  • runvenv\Scripts\activate

Now you are ready to use the freshly configured scancode-toolkit.

Note

For use in development, run insteadconfigure--dev. If your faceissues while configuring a previous version,configure--clean toclean and reset your enviroment. You will need to runconfigure again.

Installation as a library: viapip

ScanCode can be installed from the public PyPI repository usingpip whichthe standard Python package management tool.

Note

Note thatpip installation method does work on ARM chips, i.e. Linux/MacOS onApple M1 chips, as some non-native dependencies do not have pre-built wheelsfor ARM (like py-ahocorasick, intbitset). SeeSystem Requirements formore information. See related issues for more info:

The steps are:

  1. Create a Python virtual environment:

    /usr/bin/python3-mvenvvenv

For more information on Python virtualenv, visit thispage.

  1. Activate the virtual environment you just created:

    sourcevenv/bin/activate

  2. Run pip to install the latest versions of base utilities:

    pipinstall--upgradepipsetuptoolswheel

  3. Install the latest version of ScanCode:

    pipinstallscancode-toolkit

Note

For advanced usage,scancode-toolkit-mini is an alternative package withno default dependencies on pre-built binaries. This may come handy for somespecial use cases such as packaging for a Linux or FreeBSD distro.

To uninstall, run:

pipuninstallscancode-toolkit

Install from Fedora’s repository

The package is available in Fedora 40 and newer. Run:

dnfinstallscancode-toolkit

To uninstall, run:

dnfremovescancode-toolkit

Command Invocation Variations

These are the commands to invoke ScanCode based on:

  • your installation methods

  • your operating systems

The two form of commands are:

  • Use the scancode command directly, typically on Windows or in an activated virtualenv:

    scancode[OPTIONS]<OUTPUTFORMATOPTION(s)><SCANINPUT>

  • Use a path to the scancode command, typically with an application installation

    path/to/scancode[OPTIONS]<OUTPUTFORMATOPTION(s)><SCANINPUT>

These variations are summed up in the following table:

Installation Methods

Application Install

Pip Install

Install from Source Code

Linux

path:./scancode

direct: scancode

path:./scancode or direct:scancode

Mac

path:./scancode

direct: scancode

path:./scancode or direct:scancode

Windows

path:scancode

direct: scancode

path:scancode or direct:scancode