Skip to content

Conda and Bioconda Tutorial: Install Bioinformatics Tools in Environments

By Bio Help Learning42 min readUpdated FREE

Chapter 5 of 5: Troubleshooting, practice and next steps

Troubleshooting

Almost every conda problem students send us is one of these. Read the error message first: conda’s messages usually name the problem.

ProblemLikely causeWhat to do
conda: command not foundconda was not initialised, or this terminal was opened before installingRun ~/miniforge3/bin/conda init bash (zsh on macOS), then open a new terminal
fastqc: command not found right after installingThe environment is not active in this terminalconda activate qc; check with which fastqc
PackagesNotFoundErrorBioconda channels not set up, a typo in the name, or no build for your platform (native Windows, sometimes osx-arm64)conda config --show channels; conda search name; check the tool’s page on bioconda.github.io; use WSL2 on Windows
LibMambaUnsatisfiableError / “conflicts”Two packages need incompatible versions, often because of pins or a crowded environmentCreate a new environment instead of installing into an old one; split tools into separate environments; relax pins
Solving takes many minutesVery large environment, flexible priority, or defaults mixed inSet strict priority, remove defaults, keep environments small; update conda: conda update -n base conda
Packages still come from defaultsAnother .condarc file adds itconda config --show-sources; remove it there; add nodefaults to environment files
EnvironmentLocationNotFoundWrong environment name or pathconda env list and copy the exact name
Tool crashes with GLIBC_2.xx not found or a missing .so libraryMixed channels, pip installs over conda packages, or an operating system older than the build needsRecreate the environment cleanly from a file with strict priority; on old clusters use a container
CondaHTTPError or SSL errorsNetwork, proxy or institutional firewallRetry; on a campus network ask IT for proxy settings and set them in .condarc as described in the conda docs
Disk full or over quotaPackage cache and old environmentsconda clean --all; conda env remove -n old; move pkgs_dirs/envs_dirs to project storage
(base) in every promptBase auto-activation is onconda config --set auto_activate false (older conda: auto_activate_base)
▸ Go deeper: a 4-step debugging routine
  1. Where am I? conda info shows the active environment, platform and channels in one screen.
  2. Which program runs? which toolname shows whether the command comes from the environment you expect.
  3. What is installed, and from where? conda list -n env toolname shows version, build and channel.
  4. Start clean. If an environment is tangled, do not repair it package by package. Export it with --from-history, delete it and create it again. That takes minutes; untangling can take days.

🔬 Researcher notes: supply chain and trust

conda-forge and Bioconda packages are built from public recipes by automated CI and are reviewed by community maintainers, so you can read exactly how each package was built (bioconda-recipes and conda-forge feedstocks on GitHub). For sensitive or clinical work, pin exact versions, keep explicit lock files with checksums (conda list --explicit --md5), and consider a private mirror or container registry that your institute controls. Always install from the official channel names rather than look-alike channels from search results.

🔬 Researcher notes: shared lab installs

In a lab or teaching cluster, one person can maintain shared environments in a group folder with prefix paths instead of names: conda create -p /data/lab/envs/qc fastqc multiqc, and everyone runs conda activate /data/lab/envs/qc. Make the folder read-only for everyone except the maintainer, keep the matching environment.yml and lock file next to it, and never update a shared environment while someone’s analysis depends on it; create qc-2027 instead. Students still keep their own Miniforge for experiments.

Practice exercise

Do this on your own computer. It takes about 20 minutes.

  1. Make a project folder with mkdir -p ~/bhl-conda && cd ~/bhl-conda.
  2. Write an environment.yml for an environment called align with bwa, samtools (pinned with = to a recent version you see in conda search samtools, for example samtools=1.21) and fastp, using conda-forge, bioconda and nodefaults.
  3. Create it, activate it and print the versions with bwa 2>&1 | head -n 4, samtools --version | head -n 1 and fastp --version.
  4. Export it twice: conda env export -n align --from-history > align-portable.yml and conda list -n align --explicit > align-linux-64.txt. Count the lines of both with wc -l.

Answer these questions:

  • Q1. What does conda config --show channels print, and why must conda-forge be first?
  • Q2. Could a samtools=1.21 pin install a bug-fix release such as 1.21.1? What would you write to forbid that?
  • Q3. Why is align-portable.yml only a few lines long while align-linux-64.txt has dozens?
  • Q4. A labmate runs your commands and gets PackagesNotFoundError for fastp. Give two likely causes and the fixes.
SolutionSign in free to see the solution. No payment needed.Sign in / Create free account
Study material

Complete study material

  • DATAPractice environment files: qc, align and R environment.yml examples, plus a broken .condarc to fix
  • DATAScripts: setup check, Bioconda channel setup, create-from-file, three-way export and versions-for-Methods helpers
  • IPYNBGoogle Colab notebook: conda and Bioconda in your browser (condacolab)
  • PDFSlides: all diagrams, tables and a command cheat sheet (PDF, 13 slides)
  • PDFSolution with reference answers, the fixed .condarc and assignment guidance (PDF)
  • Every file above, yours to keep
  • Notebooks open in Google Colab (free)
  • Certificate with QR verification after your project report is approved

Bioconda tutorial FAQ

Is conda free for students and researchers?

Yes. conda is open source, and conda-forge and Bioconda packages are free for everyone. Only Anaconda’s own defaults channel has commercial terms for large organisations. Miniforge avoids that channel completely.

Should I use conda or mamba?

Either. Since conda 23.10, conda uses the same fast libmamba solver, so the speed difference is small. Miniforge gives you both, and the commands are the same. This tutorial uses conda because it is what most documentation and error messages refer to.

Can I use Bioconda on Windows?

Not natively. Bioconda builds for Linux and macOS only. On Windows, install WSL2 with Ubuntu and follow the Linux instructions inside it; that is also how most Windows users run bioinformatics tools.

Why is conda so slow for me?

Usually because of a very large environment, flexible channel priority, or defaults mixed with conda-forge. Check that your conda is recent (the libmamba solver is the default from 23.10), set strict priority, and create small environments in one command.

Should I install tools into base?

No. Keep base for conda itself. Tools in base can block conda updates and are easily mixed up with your project environments.

Can I use pip inside a conda environment?

Yes, as a last step and only for packages that are not on conda-forge or Bioconda. Install all conda packages first, then pip, and list pip packages in the pip: section of environment.yml. Never use pip in base.

Do I still need conda if I use Docker or Apptainer?

Usually yes, indirectly. BioContainers images are built from Bioconda packages, and many custom images install their tools with conda or micromamba. Knowing conda helps you understand and build those images.

How do I write this in my Methods?

Name conda and its version, the channels (conda-forge and Bioconda, citing Grüning et al., 2018), the exact version of each tool from conda list, and where the environment files are available. The full template is in the Researcher notes of Chapter 4.

Glossary

  • Base environment: the environment where conda itself is installed. Keep it small.
  • Channel: an online location where conda packages are published, for example conda-forge or bioconda.
  • Channel priority: the rule for choosing between channels; strict takes each package only from the highest channel that has it.
  • Environment: a separate folder with its own set of packages and its own bin/ folder.
  • Explicit file (lock file): a list of exact package URLs that rebuilds an environment without solving, for one platform.
  • MatchSpec: conda’s syntax for package requests, such as samtools=1.21 or bioconda::bwa.
  • Miniforge: a small community installer for conda and mamba that uses conda-forge by default.
  • Package cache: the folder (pkgs_dirs) where downloaded packages are stored and hard-linked into environments.
  • Prefix: the full path of an environment folder, such as ~/miniforge3/envs/qc.
  • Solver: the component that chooses a set of package versions that satisfies all dependencies.
  • Subdir: a platform folder in a channel, such as linux-64, osx-arm64 or noarch.
  • Virtual package: a system feature conda detects and treats as a package, such as __glibc or __osx.

References

  1. Grüning B, Dale R, Sjödin A, et al. Bioconda: sustainable and comprehensive software distribution for the life sciences. Nature Methods. 2018;15(7):475–476. doi:10.1038/s41592-018-0046-7
  2. Grüning B, Chilton J, Köster J, et al. Practical computational reproducibility in the life sciences. Cell Systems. 2018;6(6):631–635. doi:10.1016/j.cels.2018.03.014
  3. da Veiga Leprevost F, Grüning BA, Alves Aflitos S, et al. BioContainers: an open-source and community-driven framework for software standardization. Bioinformatics. 2017;33(16):2580–2582. doi:10.1093/bioinformatics/btx192
  4. Sandve GK, Nekrutenko A, Taylor J, Hovig E. Ten simple rules for reproducible computational research. PLoS Computational Biology. 2013;9(10):e1003285. doi:10.1371/journal.pcbi.1003285
  5. Wilson G, Bryan J, Cranston K, et al. Good enough practices in scientific computing. PLoS Computational Biology. 2017;13(6):e1005510. doi:10.1371/journal.pcbi.1005510
  6. Kurtzer GM, Sochat V, Bauer MW. Singularity: scientific containers for mobility of compute. PLoS ONE. 2017;12(5):e0177459. doi:10.1371/journal.pone.0177459
  7. Di Tommaso P, Chatzou M, Floden EW, et al. Nextflow enables reproducible computational workflows. Nature Biotechnology. 2017;35(4):316–319. doi:10.1038/nbt.3820
  8. Ewels PA, Peltzer A, Fillinger S, et al. The nf-core framework for community-curated bioinformatics pipelines. Nature Biotechnology. 2020;38(3):276–278. doi:10.1038/s41587-020-0439-x
  9. Mölder F, Jablonski KP, Letcher B, et al. Sustainable data analysis with Snakemake. F1000Research. 2021;10:33. doi:10.12688/f1000research.29032.2
  10. Beaulieu-Jones BK, Greene CS. Reproducibility of computational workflows is automated using continuous analysis. Nature Biotechnology. 2017;35(4):342–346. doi:10.1038/nbt.3780
  11. Ewels P, Magnusson M, Lundin S, Käller M. MultiQC: summarize analysis results for multiple tools and samples in a single report. Bioinformatics. 2016;32(19):3047–3048. doi:10.1093/bioinformatics/btw354
  12. Danecek P, Bonfield JK, Liddle J, et al. Twelve years of SAMtools and BCFtools. GigaScience. 2021;10(2):giab008. doi:10.1093/gigascience/giab008
  13. Li H. Aligning sequence reads, clone sequences and assembly contigs with BWA-MEM. arXiv. 2013;1303.3997. arXiv:1303.3997
  14. Bioconda documentation: usage and FAQ. bioconda.github.io
  15. conda documentation: managing environments, channels, virtual packages and conda export. docs.conda.io
  16. conda blog. Conda 23.10.0: libmamba is now the default solver. 2023. conda.org
  17. Miniforge installers (conda-forge). github.com/conda-forge/miniforge and conda-forge.org/download
  18. mamba documentation, including the Mamba 2.0 changes. mamba.readthedocs.io
  19. Anaconda Terms of Service FAQs. anaconda.com
  20. BioContainers on Quay.io. quay.io/organization/biocontainers
  21. conda-lock. github.com/conda/conda-lock; Pixi. pixi.sh

What to learn next

You can now install any bioinformatics tool safely and share your setup. Put it to work straight away:

Browse all free tutorials on the Bioinformatics Tutorials hub.

Finished this tutorial?Sign in free to mark it complete and track your progress.