Installation

Cutadapt is being developed and tested under Linux. Users have run it successfully under macOS and Windows.

Quick installation

The easiest way to install cutadapt is to use pip on the command line:

pip install --user --upgrade cutadapt

This will download the software from PyPI (the Python packaging index), and install the cutadapt binary into $HOME/.local/bin. If an old version of cutadapt exists on your system, the --upgrade parameter is required in order to install a newer version. You can then run the program like this:

~/.local/bin/cutadapt --help

If you want to avoid typing the full path, add the directory $HOME/.local/bin to your $PATH environment variable.

Installation with conda

Alternatively, cutadapt is available as a conda package from the bioconda channel. If you do not have conda, install miniconda first. Then install cutadapt like this:

conda install -c bioconda cutadapt

If neither pip nor conda installation works, keep reading.

Dependencies

Cutadapt installation requires this software to be installed:

  • Python 2.7 or at least Python 3.4

  • Possibly a C compiler. For Linux, cutadapt packages are provided as so-called “wheels” (.whl files) which come pre-compiled.

Under Ubuntu, you may need to install the packages build-essential and python-dev (or python3-dev) to get a C compiler.

On Windows, you need Microsoft Visual C++ Compiler for Python 2.7.

If you get an error message:

error: command 'gcc' failed with exit status 1

Then check the entire error message. If it says something about a missing Python.h file, then the problem are missing Python development packages (python-dev/python3-dev in Ubuntu).

System-wide installation (root required)

If you have root access, then you can install cutadapt system-wide by running:

sudo pip install cutadapt

This installs cutadapt into /usr/local/bin.

If you want to upgrade from an older version, use this command instead:

sudo pip install --upgrade cutadapt

Uninstalling

Type

pip uninstall cutadapt

and confirm with y to remove the package. Under some circumstances, multiple versions may be installed at the same time. Repeat the above command until you get an error message in order to make sure that all versions are removed.

Shared installation (on a cluster)

If you have a larger installation and want to provide cutadapt as a module that can be loaded and unloaded (with the Lmod system, for example), we recommend that you create a virtual environment and 'pip install' cutadapt into it. These instructions work on our SLURM cluster that uses the Lmod system (replace 1.9.1 with the actual version you want to use):

BASE=/software/cutadapt-1.9.1
virtualenv $BASE/venv
$BASE/venv/bin/pip install --install-option="--install-scripts=$BASE/bin" cutadapt==1.9.1

The install-option part is important. It ensures that a second, separate bin/ directory is created (/software/cutadapt-1.9.1/bin/) that only contains the cutadapt script and nothing else. To make cutadapt available to the users, that directory ($BASE/bin) needs to be added to the $PATH.

Make sure you do not add the bin/ directory within the venv directory to the $PATH! Otherwise, a user trying to run python who also has the cutadapt module loaded would get the python from the virtual environment, which leads to confusing error messages.

A simple module file for the Lmod system matching the above example could look like this:

conflict("cutadapt")
whatis("adapter trimming tool")
prepend_path("PATH", "/software/cutadapt-1.9.1/bin")

Please note that there is no need to “activate” the virtual environment: Activation merely adds the bin/ directory to the $PATH, so the prepend_path directive is equivalent to activating the virtual environment.

Installing the development version

We recommend that you install cutadapt into a so-called virtual environment if you decide to use the development version. The virtual environment is a single directory that contains everything needed to run the software. Nothing else on your system is changed, so you can simply uninstall this particular version of cutadapt by removing the directory with the virtual environment.

The following instructions work on Linux using Python 3. Make sure you have installed the dependencies (python3-dev and build-essential on Ubuntu)!

First, choose where you want to place the directory with the virtual environment and what you want to call it. Let us assume you chose the path ~/cutadapt-venv. Then use these commands for the installation:

python3 -m venv ~/cutadapt-venv
~/cutadapt-venv/bin/pip install Cython
~/cutadapt-venv/bin/pip install https://github.com/marcelm/cutadapt/archive/master.zip

To run cutadapt and see the version number, type

~/cutadapt-venv/bin/cutadapt --version

The reported version number will be something like 1.14+65.g5610275. This means that you are now running a cutadapt version that contains 65 additional changes (commits) since version 1.14.