Comprehensive Installation¶
There are four main ways to install ScanCode.
Installation as an Application: Downloading Releases
The recommended method is to download the latest application release as an application and then configure and use directly. No knowledge of pip/git or other developer tools is necessary.
-
An alternative to installing the latest Scancode Toolkit release natively is to build a Docker image from the included Dockerfile. The only prerequisite is a working Docker installation.
Installation from Source Code: Git Clone
You can clone the git source code repository and then run a configure script to configure and install ScanCode.
Installation as a library: via pip
To use ScanCode as a library in your application, you can install it via
pip
. This is recommended for developers/users familiar with Python.
Before Installing¶
ScanCode requires a Python version 3.6, 3.7, 3.8. or 3.9 and is tested on Linux, macOS, and Windows. It should work fine on FreeBSD.
System Requirements¶
Hardware : ScanCode will run best with a modern X86 processor and at least 4GB of RAM and 500MB of disk. These are bare minimum requirements.
Supported operating systems: ScanCode should run on these 64-bit OSes running X86_64 processors:
Linux: on recent 64-bit Linux distributions,
Mac: on recent 64-bit macOS (10.14 and up),
Windows: on Windows 10 and up,
FreeBSD,
Prerequisites¶
ScanCode needs a Python 3.6+ interpreter; We support all Python versions from 3.6 to 3.9.
On Linux:
Use your package manager to install
python3
.For Ubuntu, it is
sudo apt install python3-dev
On Ubuntu 14, 16, 18 and 20 run:
sudo apt install python-dev bzip2 xz-utils zlib1g libxml2-dev libxslt1-dev libpopt0
On Debian and Debian-based distros run:
sudo apt-get install python3-dev libbz2-1.0 xz-utils zlib1g libxml2-dev libxslt1-devlibpopt0
On RPM-based distros run:
sudo yum install python3.6-devel zlib bzip2-libs xz-libs libxml2-devel libxslt-devellibpopt0
On Fedora 22 and later run:
sudo dnf install python3.6-devel xz-libs zlib libxml2-devel libxslt-devel bzip2-libs libpopt0
If these packages are not available from your package manager, you must compile them from sources.
On Mac:
Download and install Python 3.6 or higher from https://www.python.org/
On Windows:
Download and install Python 3.6 or higher from https://www.python.org/
Note
64-bit Python interpreters (x86-64) are the only interpreters supported by Scancode on all operating systems which means only 64-bit Windows is supported.
See the Installation on Windows 10 section for more installation details.
Note
ScanCode app archives come with packaged with all required dependencies except for Python that has to be downloaded and installed separately.
Installation as an Application: Downloading Releases¶
Installation on Linux and Mac¶
Get the Scancode Toolkit tarball archive of a specific version and your operating system by going to the project releases page
For example, Version 21.8.1 archive can be obtained from Toolkit release 21.8.1 under assets options. Download the archive for your operating systen and extract the archive from command line:
tar -xvf scancode-toolkit-21.8.1_py39-linux.tar.xz
Or, on Linux, right click and select “Extract Here”.
Check whether the Prerequisites are installed. Open a terminal in the extracted directory and run:
./scancode --help
This will configure ScanCode and display the command line Help text.
Installation on Windows 10¶
Download the latest ScanCode release zip file for Windows from the latest version at https://github.com/nexB/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 10, 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 and close 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 and then Right-click in this window and select Paste. This will paste the path you copied before and is where you extracted ScanCode:
cd path/to/extracted_ScanCode
Press Enter.
This will change the current location of your command prompt to the root directory where ScanCode 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 directory under a scanCode-prefixed directory.
Installation via Docker:¶
You can install Scancode Toolkit by building a Docker image from the included Dockerfile. The prerequisite is a working docker installation.
Download the ScanCode-Toolkit Source Code¶
Either download the Source Code for one of the releases ( Installation as an Application: Downloading Releases ) and unzip it.
Or
git clone https://github.com/nexB/scancode-toolkit
to get the latest ( Installation from Source Code: Git Clone ) Source Code.
Build the Docker image¶
The docker build
command needs to run in the directory of the source code,
make sure to cd
into the correct directory.:
cd scancode-toolkit
docker build -t scancode-toolkit .
Run using Docker¶
The docker image will forward all arguments it receives directly to the scancode
command.
Display help:
docker run scancode-toolkit --help
Mount current working directory and run scan on mounted folder:
docker run -v $PWD/:/project scancode-toolkit -clpeui --json-pp /project/result.json /project
This will mount your current working from the host into /project
in the container
and then scan the contents. The output result.json
will be written back to your
current working directory on the host.
Note that the parameters before scancode-toolkit
are used for docker,
those after will be forwarded to scancode.
Installation from Source Code: Git Clone¶
You can also download the Scancode Toolkit Source Code and build from it yourself. This is how you would want to do it if:
You are adding new patches to Scancode and want to test it. So you build ScanCode locally with your added changes.
You want to test a specific version/checkpoint/branch from the VCS.
Download the ScanCode-Toolkit Source Code¶
If you don’t have the ScanCode Toolkit Source Code downloaded, get it from its official Repository (Downloaded as a .zip file)
Or you can run the following if you have Git installed:
git clone https://github.com/nexB/scancode-toolkit.git
cd scancode-toolkit
Now, by default the files are checked out to the develop branch, but you can jump to any checkpoint using the following command:
git checkout develop
Here, develop
branch has the latest release of Scancode-Toolkit.
You can also check out to any of the following:
Branches (Locally created or already present) [Example -
develop
]Tags (essentially version numbers) [Example -
v21.8.1
,v21.5.31
]Commits (use the shortened commit hash) [Example -
4502055
,f276398
]
Configure the build¶
ScanCode use the Configure scripts to install a virtualenv, install required packaged dependencies as pip requirements and more configure tasks such that ScanCode can be installed in a self-contained way with no network connectivity required.
On Linux/Mac:
Open a terminal
cd to the clone directory
run
./configure
run
source bin/activate
On Windows:
open a command prompt
cd to the clone directory
run
configure
run
Scripts\activate
Now you are ready to use the freshly configured scancode-toolkit.
Note
For use in development, run instead configure --dev
. If your face
issues while configuring a previous version, configure --clean
to
clean and reset your enviroment. You will need to run configure
again.
Installation as a library: via pip
¶
ScanCode can be installed using pip
, the default Python Package Manager.
The steps are:
Create a Python virtual environment:
/usr/bin/python3 -m venv .
For more information on Python virtualenv, visit this page.
Activate the virtual environment you just created:
source bin/activate
Run
pip install --upgraded pip setuptools wheel
to install the latest versions of base utilities.Run
pip install scancode-toolkit
to install the latest version of ScanCode.
Note
For advanced usage, scancode-toolkit-mini
is an alternative package with
no default dependencies on pre-built binaries. This may come handy for some
special use cases such as packaging for a Linux or FreeBSD distro.
To uninstall, run pip uninstall scancode-toolkit
.
Commands Variation¶
The commands to run ScanCode varies for:
Different Installation Methods
OS used
The two types of commands are:
scancode [OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
path/to/scancode OPTIONS] <OUTPUT FORMAT OPTION(s)> <SCAN INPUT>
In the second case, ./scancode
is used if already in the directory.
These variations are summed up in the following table:
Installation Methods |
Application Install |
Pip Install |
Install from Source Code |
---|---|---|---|
Linux |
./scancode |
scancode |
./scancode |
Mac |
./scancode |
scancode |
./scancode |
Windows |
scancode |
scancode |
scancode |
To sum it up, scancode
is used in these two cases:
If
pip
install is used.If the OS is Windows.
In all other cases, ./scancode
is used.