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 pip3
on the command line:
python3 -m 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. Install miniconda if you don’t have Conda. Then follow the Bioconda installation instructions (in particular, make sure you have both bioconda and conda-forge in your channels list).
To then install Cutadapt into a new Conda environment, use this command:
conda create -n cutadaptenv cutadapt
Here, cutadaptenv
is the name of the Conda environment. (You can
choose a different name.)
An environment needs to be activated every time you want to use the programs in it:
conda activate cutadaptenv
Finally, check whether it worked:
cutadapt --version
This should show the Cutadapt version number.
Installation on a Debian-based Linux distribution¶
Cutadapt is also included in Debian-based Linux distributions, such as Ubuntu. Simply use your favorite package manager to install Cutadapt. On the command-line, this should work
sudo apt install cutadapt
or possibly
sudo apt install python3-cutadapt
Please be aware that this will likely give you an old version of Cutadapt. If you encounter unexpected behavior, please use one of the other installation methods to get an up-to-date version before reporting bugs.
Dependencies¶
Cutadapt installation requires this software to be installed:
- Python 3.4 or newer
- 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
python3-dev
to get a C compiler.
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 is that you are missing Python development
packages (python3-dev
in Ubuntu).
System-wide installation (root required)¶
If you have root access, then you can install Cutadapt system-wide by running:
sudo python3 -m pip install cutadapt
This installs cutadapt into /usr/local/bin
.
If you want to upgrade from an older version, use this command instead:
sudo python3 -m pip install --upgrade cutadapt
If the above does not work for you, then you can try to install Cutadapt into a virtual environment. This may lead to fewer conflicts with system-installed packages:
sudo python3 -m venv /usr/local/cutadapt
sudo /usr/local/cutadapt/bin/pip install cutadapt
cd /usr/local/bin/
sudo ln -s ../cutadapt/bin/cutadapt
Uninstalling¶
Type
pip3 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.
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/python3 -m pip install --upgrade pip
~/cutadapt-venv/bin/pip install git+https://github.com/marcelm/cutadapt.git#egg=cutadapt
To run Cutadapt and see the version number, type
~/cutadapt-venv/bin/cutadapt --version
The reported version number will be something like 2.2.dev5+gf564208
. This
means that you are now running the version of Cutadapt that will become 2.2, and that it contains
5 changes (commits) since the previous release (2.1 in this case).