====== Installing Software with Conda ======

Conda (via Miniconda) lets you install and manage software in your own user space without needing admin access. This is the recommended way to install tools that are not available system-wide.

===== When to Use Conda =====

  * You need a tool that is not installed on the cluster.
  * You need a **specific version** of a tool.
  * You need an isolated environment to avoid conflicts between tools.
  * You want to reproduce an environment from a collaborator.

If the tool you need is already installed system-wide, you do not need Conda. Check with ''which <tool_name>'' first.

----

===== Step 1: Install Miniconda =====

Miniconda is a minimal Conda installer. You only need to do this once.

<code bash>
# Download the installer
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# Run the installer
bash Miniconda3-latest-Linux-x86_64.sh
</code>

During installation:
  - Press **Enter** to review the license, then type **yes** to accept.
  - Press **Enter** to accept the default install location (''~/miniconda3''), or specify a custom path.
  - **When asked "Do you wish the installer to initialize Miniconda3 by running conda init?", type ''no''.**

> **Important: Do NOT let Conda modify your ''~/.bashrc''.** Conda initialization in bashrc runs every time you log in or open a shell, significantly slowing down SSH logins. Instead, activate Conda manually when you need it (see below).

After installation, verify it works by sourcing it manually:

<code bash>
source ~/miniconda3/etc/profile.d/conda.sh
conda --version
conda list
</code>

=== Clean up the installer ===

<code bash>
rm Miniconda3-latest-Linux-x86_64.sh
</code>

=== Activating Conda ===

Since Conda is **not** in your bashrc, you need to activate it manually each time you want to use it:

<code bash>
source ~/miniconda3/etc/profile.d/conda.sh
conda activate myproject
</code>

You can create a short alias in your ''~/.bashrc'' for convenience:

<code bash>
alias conda-init='source ~/miniconda3/etc/profile.d/conda.sh'
</code>

Then when you need Conda, just type:

<code bash>
conda-init
conda activate myproject
</code>

----

===== Step 2: Create an Environment =====

**Always create a separate environment for each project or tool.** Do not install everything into the ''base'' environment.

<code bash>
# Create a new environment named "myproject" with Python 3.11
conda create -n myproject python=3.11

# Activate it
conda activate myproject
</code>

Your prompt changes to ''(myproject)'', indicating you are in the environment.

----

===== Step 3: Install Packages =====

<code bash>
# Install from the default channel
conda install numpy pandas matplotlib

# Install from the bioconda channel (bioinformatics tools)
conda install -c bioconda -c conda-forge bwa samtools

# Install a specific version
conda install -c bioconda gatk4=4.4.0.0
</code>

=== Bioconda ===

Most bioinformatics tools are available through the **bioconda** channel. Always include ''-c conda-forge'' along with ''-c bioconda'' for dependency resolution:

<code bash>
conda install -c bioconda -c conda-forge fastqc multiqc fastp
</code>

To search for a tool:

<code bash>
conda search -c bioconda <tool_name>
</code>

Or visit [[https://bioconda.github.io/|bioconda.github.io]] to browse available packages.

----

===== Managing Environments =====

<code bash>
# List all environments
conda env list

# Activate an environment
conda activate myproject

# Deactivate (go back to base)
conda deactivate

# Remove an environment entirely
conda env remove -n myproject

# List packages in the current environment
conda list
</code>

=== Export and share an environment ===

To share your environment with a collaborator:

<code bash>
# Export to a YAML file
conda env export > environment.yml

# The collaborator can recreate it with:
conda env create -f environment.yml
</code>

----

===== Using Conda with Slurm =====

When submitting Slurm jobs, you need to activate the Conda environment inside your job script:

<code bash>
#!/bin/bash
#SBATCH --mem=10gb
#SBATCH --cpus-per-task=4
#SBATCH --output=log/my_job_%j.log

# Initialize conda for the batch shell
source ~/miniconda3/etc/profile.d/conda.sh

# Activate the environment
conda activate myproject

# Now you can use tools from this environment
fastqc -o fastqc_results/ fastq/*.fq.gz

echo "Done!"
</code>

**Important:** The ''source ~/miniconda3/etc/profile.d/conda.sh'' line is necessary because (a) Slurm jobs start a non-interactive shell, and (b) at ABI we do not add Conda to ''~/.bashrc'' to keep logins fast.

----

===== Tips =====

  * **Do not install tools in the base environment.** Create separate environments per project.
  * **Use ''conda-forge'' as a default channel.** It has better dependency resolution:
<code bash>
conda config --add channels conda-forge
conda config --set channel_priority strict
</code>
  * **Use ''mamba'' for faster installs** (optional):
<code bash>
conda install -n base -c conda-forge mamba
mamba install -c bioconda bwa    # Much faster than conda install
</code>
  * **Storage considerations:** Conda environments can become large. Your home directory has only ~12G quota. If your environments grow large, consider installing Miniconda under ''/mnt/nas0/user/<your_username>/miniconda3'' instead (which has ~100G). Check your disk usage with:
<code bash>
du -sh ~/miniconda3/
du -sh ~/miniconda3/envs/*/
</code>

----

===== Troubleshooting =====

^ Problem ^ Solution ^
| ''conda: command not found'' | Run ''source ~/miniconda3/etc/profile.d/conda.sh'' to activate Conda for this session. |
| ''(base)'' not showing in prompt | This is expected at ABI since we do not add Conda to bashrc. Run ''source ~/miniconda3/etc/profile.d/conda.sh'' first. |
| Package conflict / solver hangs | Try using ''mamba'' instead of ''conda''. Or create a fresh environment. |
| Disk quota exceeded | Clean unused packages: ''conda clean --all''. Remove old environments. |
| Tool not found after ''conda activate'' | Make sure you installed the tool in the correct environment: ''conda list | grep <tool>'' |

----

===== See Also =====

  * [[https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html|Conda Getting Started Guide]]
  * [[https://bioconda.github.io/|Bioconda -- Bioinformatics packages for Conda]]
  * [[software:start|Software Overview]]
  * [[software:slurm|Using Slurm]] -- how to use Conda environments in Slurm jobs