Skip to content
Shell bootloader for bioinformatics.
Shell R Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

koopa 🐢

Travis CI build status Repo status: active

Shell bootloader for bioinformatics.


These POSIX-compliant shells are supported: bash, zsh.


  • Linux or macOS. Windows isn't supported.
  • Bash >= 4. Required even when using a different shell.
  • Python >= 3.7.
  • R >= 3.6.

Tested on:

  • macOS Mojave
  • Ubuntu 18 LTS
  • Debian Buster
  • RHEL 8 / CentOS 8
  • RHEL 7 / CentOS 7
  • Amazon Linux 2

Shared user installation

Recommended. This requires sudo permissions.

Clone the repository.

sudo mkdir -p "$koopa_dir"

# - darwin (macOS): admin
# - debian: sudo
# - fedora: wheel

sudo chgrp "$group" "$koopa_dir"
sudo chmod g+w "$koopa_dir"

git clone --recursive "$koopa_dir"

This will add a shared profile configuration file at /etc/profile.d/ for supported Linux distros.

If you're going to install any programs using the cellar scripts, also adjust the permissions for /usr/local/. Otherwise the link cellar commands will error and you will see symlink errors.

sudo chgrp -Rh "$group" /usr/local
sudo chmod g+w -R /usr/local
sudo chmod g+s /usr/local

Local user installation

Use this approach on machines without sudo permissions.

Clone the repository. Installation following the XDG base directory specification is recommended.

# ~/.local/share/koopa
mkdir -p "$koopa_dir"
git clone --recursive "$koopa_dir"

Add these lines to your shell configuration file.

# koopa shell
# shellcheck source=/dev/null
. "${HOME}/.local/share/koopa/activate"

Check installation

Restart the shell. Koopa should now activate automatically at login. You can verify this with command -v koopa. Next, check your environment dependencies with koopa check. To obtain information about the working environment, run koopa info.


Shell configuration file

Not sure where to source activate in your configuration? Here are some general recommendations, in order of priority for each shell. These can differ depending on the operating system, so refer to your shell documentation for details.

  • bash: .bash_profile, .bashrc.
  • zsh: .zshrc, .zprofile.
  • ksh: .kshrc, .profile.

Exported tools

Upon activation, koopa makes scripts available in $PATH, which are defined in the bin/ directory of the repo. Run koopa list for a complete list.

Automatic program configuration

Koopa provides automatic configuration and $PATH variable support for a number of popular bioinformatics tools. When configuring manually, ensure that variables are defined before sourcing the activation script.

Aspera Connect

Aspera Connect is a secure file transfer application commonly used by numerous organizations, including the NIH and Broad Institute. Koopa will automatically detect Aspera when it is installed at the default path of ~/.aspera/. Otherwise, the installation path can be defined manually using the $ASPERA_EXE variable.

export ASPERA_EXE="${HOME}/.aspera/connect/bin/asperaconnect"


bcbio is a Python toolkit that provides modern NGS analysis pipelines for RNA-seq, single-cell RNA-seq, ChIP-seq, and variant calling. Koopa provides automatic configuration support for the Harvard O2 and Odyssey high-performance computing clusters. Otherwise, the installation path can be defined manually using the $BCBIO_EXE variable.

export BCBIO_EXE="/usr/local/bin/"


Conda is an open source package management system that provides pre-built binaries using versioned recipes for Linux and macOS.

Koopa provides automatic detection and activation support when conda is installed at any of these locations (note priority):

  • ~/anaconda3/
  • ~/miniconda3/
  • /usr/local/anaconda3/
  • /usr/local/miniconda3/

Oherwise, the installation path can be defined manually using the $CONDA_EXE variable.

export CONDA_EXE="${HOME}/miniconda3/bin/conda"

SSH key

On Linux, koopa will launch ssh-agent and attempt to import the default SSH key at ~/.ssh/id_rsa, if the key file exists. A different default key can be defined manually using the $SSH_KEY variable.

export SSH_KEY="${HOME}/.ssh/id_rsa"

On macOS, instead we recommend adding these lines to ~/.ssh/config to use the system keychain:

Host *
    AddKeysToAgent yes
    IdentityFile ~/.ssh/id_rsa
    UseKeychain yes
You can’t perform that action at this time.