PipeCraft2 Logo
  • Installation
    • Prerequisites
    • Windows
    • MacOS
    • Linux
    • Updating PipeCraft2
    • Uninstalling PipeCraft2
    • Manage resources allocated to Docker
    • Purging ‘old’ Docker installations
    • Removing Docker images
  • QuickStart
  • Pre-compiled pipelines
  • Individual steps (Quick Tools)
  • Post-processing tools
  • Example data analyses
  • Troubleshooting
  • Licence
  • How to cite
  • Releases
  • Docker images
  • Contact and Acknowledgements
  • For Developers
PipeCraft2
  • Installation
  • View page source

Installation PipeCraft2_logo

Installation packages are available for Windows, Mac and Linux.

Current versions do not work on High Performance Computing (HPC) clusters yet.

Herein ‘PipeCraft’ == ‘PipeCraft2’. Using those interchangeably.

Prerequisites

  1. ADMIN rights to install software. Required to install Docker, and since PipeCraft2 app is not “signed” (for Windows and Linux [ok for MacOS]) then executing this requires also admin rights.

  2. Docker. See OS-specific (Windows, Mac, Linux) docker installation guidelines below.

Why Docker is needed?

Modules of PipeCraft2 are distributed through Docker containers, which will liberate the users from the struggle to install/compile various software for metabarcoding data analyses. Thus, all backend bioinformatics processes are run in Docker containers. Relevant Docker container will be automatically downloaded prior the analysis. See below how to manage and remove Docker images for the system.


Windows

PipeCraft2 was tested on Windows 10 and Windows 11. Older Windows versions do not support PipeCraft GUI workflow through Docker.

  1. Download installer for Windows: PipeCraft2 v1.2.0

  2. Install PipeCraft2 via the setup executable.

False alert

Your OS might warn that PipeCraft2 is dangerous software! Please ignore the warning until this issue is fixed by the developers.

  1. Download Docker for windows - ONLY ONCE (no need, when updating PipeCraft).

    Important

    Administrator privileges are required during installation. Once installed, Docker on Windows can be run without admin rights.

Warning

In Windows, please keep you working directory path as short as possible. Maximum path length in Windows is 260 characters. PipeCraft may not be able to work with files, that are buried “deep inside” (i.e. the path is too long).

Note

Resource limits for Docker are managed by Windows; but you can configure limits in a .wslconfig file, but this can be automatically done via PipeCraft GUI, see Manage resources allocated to Docker. Default = 50% of total memory on Windows or 8GB, whichever is less. 80% of total memory on Windows on builds before 20175 (Win10, from 2020).



Quick guide to increase Docker accessible RAM size in Windows:

This is a legacy guide; please use the PipeCraft GUI to manage Docker resources, see Manage resources allocated to Docker.

Instructions from https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconfig

  1. This is for Windows Build 19041 and later with WSL 2

  2. Open ‘File Explorer’ and type %USERPROFILE% to the address bar to access the %USERPROFILE% directory (generally e.g. “C:Usersmy_user_name”).

  3. Make new text (txt) document into %USERPROFILE% directory.

  4. Paste the following text to that new txt document:

make .wslconfig file
 # Settings apply across all Linux distros running on WSL 2
 [wsl2]

 # Limits VM memory to use no more than X GB, this can be set as whole numbers using GB or MB
 memory=30GB

 # Sets the VM to use X virtual processors
 processors=8

  1. Edit “memory=30GB” and “processors=8” according to your needs

  2. Save the file and rename this as .wslconfig

  3. Restart Docker.


MacOS

PipeCraft2 is supported on macOS 10.15+. Older OS versions might not support PipeCraft GUI workflow through Docker.

Note

If your MacOS has M1/M2 chips, please let us know if you encounter something weird while trying to run some analyses (contact or post an issue on the github page).

  1. Download for Mac: PipeCraft2 v1.2.0

  2. Install PipeCraft2 via downloaded dmg file by double-clicking on the file and dragging the app to the Applications folder.

  3. Check your Mac chip (Apple or Intel) and download Docker for Mac - ONLY ONCE (no need, when updating PipeCraft)

  1. Open Docker dashboard: Settings -> Resources -> File Sharing; and add the directory where pipecraft.app was installed (it is usually /Appications)

mac_docker_share

Note

Manage Docker resource limits in the Docker dashboard or Resource Manager in PipeCraft GUI. resources

Note

On Apple silicon, tick Use Rosetta for x86_64/amd64 emulation in Docker Desktop settings.

rosetta


Linux

PipeCraft2 was tested with Ubuntu 20.04 and Mint 20.1. Older OS versions might not support PipeCraft GUI workflow through Docker.

  1. Download for Linux: PipeCraft2 v1.2.0

  2. Right click the .AppImage file, go to Properties, and check “Allow executing file as program”, then simply run Pipecraft2 by double-clicking the Appimage.

    Note

    Latest Ubuntu versions require a library called libfuse2t64 to run AppImages. Open your terminal and run: sudo apt install libfuse2t64

    If you are having trouble launching the AppImage, try starting it from the terminal for more feedback:

    chmod +x pipecraft-1.2.0-linux-x86_64.AppImage && ./pipecraft-1.2.0-linux-x86_64.AppImage

  3. Install Docker - ONLY ONCE (no need, when updating PipeCraft); follow the guidelines under appropriate Linux distribution

    Warning

    When installing Docker Engine, make sure you have not Docker Desktop already installed!
    Installing both might have interfering consequences

  1. If you are a non-root user complete these post-install steps

Note

When you encounter ERROR during PipeCraft2 installation, then uninstall the previous version of PipeCraft2 sudo dpkg --remove pipecraft-v0.1.3

  1. Run PipeCraft2. If PipeCraft shortcut does not appear on the Desktop, then search the app and generate shortcut manually (installed in /opt/pipecraft directory)

Note

On Linux, Docker can use all available host resources.


Updating PipeCraft2

From version 1.2.0 onwards, PipeCraft2 will automatically check for updates on startup and notify the user. To manually check for updates, click on the update icon in the bottom-right corner.

auto_update

When updating PipeCraft2, it is recommended to remove previous Docker images associated with previous PipeCraft2 versions. This simply helps to save disk space, since each PipeCraft2 version has its own Docker images. See removing docker images section.

See PipeCraft2 releases here.

Warning

To avaoid any potential software conflicts from PipeCraft2 v0.1.1 to v0.1.4, all Docker images of older PipeCraft2 version should be removed.
Starting from v1.0.0, if docker container is updated for the new PipeCraft2 version, then it will get a new tag; so, no need to purge all previous docker containers (but to save disk space, see which containers you have not used for a while and perhaps delete those)

Uninstalling PipeCraft2

Windows: uninstall PipeCraft via control panel
MacOS: Move pipecraft.app to Bin
Linux: Delete the AppImage file or if running an older deb package, remove pipecraft via Software Manager/Software Centre or via terminal:
sudo dpkg --remove pipecraft

Manage resources allocated to Docker

resource_manager

Resource management in PipeCraft2 allows to control and limit the resources (such as number of CPUs, RAM) that Dockercontainers can use. You can control these settings also easily through PipeCraft GUI, by clicking on the Docker icon in the top-right corner of the PipeCraft window. After editing, press the APPLY & RESTART DOCKER button, so that the changes would take effect.

Docker engine must be running (the icon must be green) in order to apply the changes.

Required amont of allocated resources depends generally on the input data size and the complexity of the analysis. If too few RAM is allocated, then the analysis may fail without any informative ERROR message. If too few CPU cores are allocated, then the analysis may be very slow. The more the merrier, but when allocating most of your computer’s resources, please keep in mind that there will be fewer resources available for other processes on your computer.


Purging ‘old’ Docker installations

To uninstall docker engine and all its packages:
 sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
To uninstall docker desktop and clean configurations:
    rm -r $HOME/.docker/desktop
    sudo rm /usr/local/bin/com.docker.cli
    sudo apt purge docker-desktop

Removing Docker images

On MacOS and Windows: Docker images and container can be easily managed from the Docker dashboard. For more info visit https://docs.docker.com/desktop/dashboard/
See command-line based way below.

purge_docker_Win


On Linux machines: containers and images are managed via the Docker cli commands (https://docs.docker.com/engine/reference/commandline/rmi/):
sudo docker images –> to see which docker images exist
sudo docker rmi IMAGE_ID –> to delete selected image

or

sudo docker system prune -a –> to delete all unused containers, networks, images
sudo docker images –> check if images were removed
Previous Next

© Copyright 2026, Sten Anslan.

Built with Sphinx using a theme provided by Read the Docs.