Contributing a recipe

The following steps are done for each recipe or batch of recipes you’d like to contribute.

1. Update repo

If you’re using a fork (set up as above):

git checkout master
git pull upstream master
git push origin master

If you’re using a clone:

git checkout master
git pull origin master

2. Write a recipe

Check out a new branch (here the branch is arbitrarily named “my-recipe”):

git checkout -b my-recipe

and write one or more recipes. The conda-build docs are the authoritative source for information on building a recipe.

Please familiarize yourself with the Guidelines for bioconda recipes for details on bioconda-specific policies.

3. Test locally (optional)

There are currently two options for local testing: 1) using the Circle CI client and 2) setting up a separate Miniconda installation and running bioconda-utils. The first is potentially simpler to set up but less flexible.


If you use the Circle CI client method and receive errors then please try bioconda-utils build instead.

Circle CI client method

The simplest way to conduct local tests is to setup the Circle CI client. Then run the following commands:

# Ensure the build container is up-to-date
docker pull bioconda/bioconda-utils-build-env

# Run the build locally
circleci build

in the root of your repository clone. This command effectively runs the recipe linting and then conda build on all recipes recently changed. It does so in an environment with properly configured channels.

“Bootstrap” method

Due to technical limitations of the Circle CI client, the above test does not run the more stringent mulled-build tests. To do so, use the following commands:

./ /tmp/miniconda
source ~/.config/bioconda/activate

# optional linting
bioconda-utils lint recipes config.yml --git-range master

# build and test
bioconda-utils build recipes config.yml --docker --mulled-test --git-range master

The above commands do the following:

  • install a separate miniconda installation in a temporary directory, set up bioconda channels, install bioconda-utils dependencies into the root environment of that installation, and write the file ~/.config/bioconda/activate

  • source that new file to specifically activate the root environment of that new installation

  • run bioconda-utils in that new installation

If you do not have access to Docker, you can still run the basic test by telling the bootstrap setup to not use docker, and by excluding the --docker and --mulled-test arguments in the last command:

./ --no-docker /tmp/miniconda
source ~/.config/bioconda/activate
bioconda-utils build recipes config.yml --git-range master

Updating recipes

bioconda-utils now has the ability to automatically update packages and submit a PR on your behalf. Note that the auto-updater does not yet know how to monitor changed dependencies, so it is important to verify that the updated recipe reflects all the changes. This tool is most useful when scanning packages to know when something has been updated.

bioconda-utils update recipes/ config.yml --packages <my-package-name>

will update the package’s recipe which you can then inspect. If you have a GitHub personal access token set as the environment variable GITHUB_TOKEN, the following command will additionally submit a pull request on your behalf:

bioconda-utils update recipes/ config.yml \
  --packages <my-package-name> \

For more details, see the Updating recipes section.

4. Push changes, wait for tests to pass, submit pull request

Push your changes to your fork or to the main repo (if using a clone) to GitHub:

git push -u origin my-recipe


Update March 2018: If using a fork, please do not enable Circle CI for it. If you have enabled CircleCI to build your fork in the past, please disable it under (look for the big red “Stop Building” button). See CircleCI macOS plans for more details.

You can view the test status next to your commits in Github. Make and push changes as needed to get the tests to pass. Once they pass, create a pull request on the main bioconda repo for your changes. If

  • it’s your first recipe,

  • the recipe is doing something non-standard or

  • it adds a new package

please ask @bioconda/core for a review. If you are a member of the bioconda team and none of above criteria apply, feel free to merge your recipe once the tests pass.

6. Use your new recipe

When the PR is merged with the master branch, Circle CI will again do the builds but at the end will upload the packages to Once this completes, and as long as the channels are set up as described in 2. Set up channels, your new package is installable by anyone using:

conda install my-package-name

It is recommended that users set up channels as described in 2. Set up channels to ensure that packages and dependencies are handled correctly, and that they create an isolated environment when installing using conda create -n env-name-here.