Skip to main content

Configuring conda-forge.yml

You can configure how conda-forge is set up and built via the conda-forge.yml file that is present in the root directory of a feedstock.

Rerendering the feedstock after you modify this file is usually required and always a good idea (see Rerendering feedstocks).

The next section describes in detail the top-level fields in conda-forge.yml.

Note that each top-level CI provider field supports the upload_packages option. When set to False this will override the default behaviour of attempting to upload packages to anaconda.org, which can be useful for testing. For example:

azure:
  upload_packages: False

Top-level fields​

appveyor​

The top-level appveyor key specifies configurations for the Appveyor CI service. This is usually read-only and should not normally be manually modified. Tools like conda-smithy may modify this, as needed.

azure​

This dictates the behavior of the Azure Pipelines CI service. It is a mapping for Azure-specific configuration options. For example:

azure:
  # flag for forcing the building all supported providers
  force: False
  # toggle for storing the conda build_artifacts directory (including the
  # built packages) as an Azure pipeline artifact that can be downloaded
  store_build_artifacts: False
  # toggle for freeing up some extra space on the default Azure Pipelines
  # linux image before running the Docker container for building
  free_disk_space: False
  # limit the amount of CI jobs running concurrently at a given time
  # each OS will get its proportional share of the configured value
  max_parallel: 25
  # set the timeoutInMinutes field for jobs in the azure pipeline.
  # jobs that take longer than this will be cancelled.
  # default: 360 (6 hours)
  timeout_minutes: 360
  # can also be set per-platform via
  # settings_linux:
  #   timeoutInMinutes: 360

Below is an example configuration for setting up a self-hosted Azure agent for Linux:

azure:
  settings_linux:
    pool:
      name: your_local_pool_name
      demands:
        - some_key -equals some_value
    workspace:
      clean: all
    strategy:
      maxParallel: 1
    timeoutInMinutes: 360

Below is an example configuration for adding a swapfile on an Azure agent for Linux:

azure:
  settings_linux:
    swapfile_size: 10GiB

To increase the pagefile size on Windows, use this block:

azure:
  settings_win:
    variables:
      SET_PAGEFILE: 'True'

bot​

This field controls the behavior of the auto-tick bot which issues automatic version updates/migrations for feedstocks. The current options are

bot:
  # can the bot automerge PRs it makes on this feedstock
  automerge: true
  # only automerge on successful version PRs, migrations are not automerged
  automerge: 'version'
  # only automerge on successful migration PRs, versions are not automerged
  automerge: 'migration'

  # only open PRs if resulting environment is solvable, useful for tightly coupled packages
  check_solvable: true

  # The bot.inspection key in the conda-forge.yml can have one of six possible values:
  inspection: hint  # generate hints using source code (backwards compatible)
  inspection: hint-all  # generate hints using all methods
  inspection: hint-source  # generate hints using only source code
  inspection: hint-grayskull  # generate hints using only grayskull
  inspection: update-all  # update recipe using all methods
  inspection: update-source  # update recipe using only source code
  inspection: update-grayskull  # update recipe using only grayskull

  # any branches listed in this section will get bot migration PRs in addition
  # to the default branch
  abi_migration_branches:
    - v1.10.x

  version_updates:
    # use this for packages that are updated too frequently
    random_fraction_to_keep: 0.1  # keeps 10% of versions at random

The abi_migration_branches feature is useful to, for example, add a long-term support (LTS) branch for a package.

build_platform​

This is a mapping from the target platform to the build platform for the package to be built. e.g. the following builds a osx-64 package on the linux-64 build platform using cross-compiling.

build_platform:
  osx_64: linux_64

Leaving this field empty implicitly requests to build a package natively. i.e.

build_platform:
  linux_64: linux_64
  linux_ppc64le: linux_ppc64le
  linux_aarch64: linux_aarch64
  osx_64: osx_64
  osx_arm64: osx_arm64
  win_64: win_64

build_with_mambabuild​

warning

This option has been deprecated. See conda_build_tool for more information.

channel_priority​

This value sets the conda solver channel priority for feedstock builds. The default is strict. Any valid value for the same setting in the .condarc is allowed here.

channels​

warning

This parameter has been deprecated. Instead, specify channels in recipe/conda_build_config.yaml using channel_sources and channel_targets. Note that all channels go on a single line because each line represents a build variant.

recipe/conda_build_config.yaml
channel_sources:
  - mysourcechannel1,mysourcechannel2,conda-forge,defaults
channel_targets:
  - target_channel target_label

choco​

This parameter allows for conda-smithy to run chocoloatey installs on Windows when additional system packages are needed. This is a list of strings that represent package names and any additional parameters. For example,

choco:
  # install a package
  - nvidia-display-driver

  # install a package with a specific version
  - cuda --version=11.0.3

This is currently only implemented for Azure Pipelines. The command that is run is choco install {entry} -fdv -y --debug. That is, choco install is executed with a standard set of additional flags that are useful on CI.

circle​

The top-level circle key specifies configurations for the Circle CI service. This is usually read-only and should not normally be manually modified. Tools like conda-smithy may modify this, as needed.

conda_build​

Settings in this block are used to control how conda build runs and produces artifacts. The currently supported options are

conda_build:
  pkg_format: 2    # makes .conda artifacts
  pkg_format: None # makes .tar.bz2 artifacts
  # controls the compression level for .conda artifacts
  # conda-forge uses a default value of 16 since its artifacts
  # can be large. conda-build has a default of 22.
  zstd_compression_level: 16

conda_build_tool​

Use this option to choose which tool is used to build your recipe. Currently allowed options are:

  • conda-build: Vanilla conda build ... with no explicit solver configuration. Note that it will still respect the value configured in conda_solver, if any.
  • conda-build+classic: conda build ... with the classic solver enforced.
  • conda-build+conda-libmamba-solver: conda build ... with the conda-libmamba-solver solver enforced.
  • mambabuild: conda mambabuild ... as provided by boa.

conda_forge_output_validation​

This field must be set to True for feedstocks in the conda-forge GitHub organization. It enables the required feedstock artifact validation as described in Output Validation and Feedstock Tokens.

conda_install_tool​

Use this option to choose which tool is used to provision the tooling in your feedstock. Currently allowed options are:

  • conda: conda install .... You can change which solver to use via conda_solver.
  • mamba: mamba install ... as provided by the mamba project. conda_solver has no effect here.

conda_solver​

Choose which conda solver plugin to use for feedstock builds. Note this configuration might affect conda_build_tool (e.g. when set to conda-build) and conda_install_tool (e.g. when set to conda).

docker​

This is a mapping to docker configuration options. These are relatively self-explanatory. The defaults are as follows:

docker:
  executable: docker
  image: "condaforge/linux-anvil-comp7"
  command: "bash"
  interactive: True

github​

This is mapping of configuration variables for GitHub. The defaults are as follows:

github:
  # name of the github organization
  user_or_org: conda-forge
  # repository name, usually filled in automatically
  repo_name: ""
  # branch name to execute on
  branch_name: main
  # branch name to use for rerender+webservices github actions and
  # conda-forge-ci-setup-feedstock references
  tooling_branch_name: main

github_actions​

This dictates the behavior of the Github Actions CI service. It is a mapping for GHA-specific configuration options. For example:

github_actions:
  # Is the job using Microsoft hosted free runners or 'self-hosted'.
  self_hosted: false
  # triggers for actions. Defaults to `['push', 'pull_request']` for
  # Microsoft hosted free runners and `['push']` for self-hosted
  triggers: []
  # Timeout for CI jobs
  timeout_minutes: 360
  # Cancel in progress builds. Defaults to false for Microsoft hosted
  # free runner and true for self-hosted
  cancel_in_progress: None
  # Maximum number of parallel jobs per build.
  max_parallel: None
  # Retain build artifacts for inspection
  store_build_artifacts: false
  # Retention period for built artifacts
  artifact_retention_days: 14

For self-hosted runners recipe/conda_build_config.yaml is used for specifying labels for the runners.

github_actions_labels:
  # use Microsoft free runners
  - hosted                                   # [osx or win]
  # Use self-hosted runner with custom label
  - - self-hosted                            # [linux and aarch64]
    - custom-label                           # [linux and aarch64]
  # Use self-hosted runner from cirun
  - cirun-openstack-cpu-large                # [linux and ppc64le]
  # Use self-hosted gpu runner from cirun
  - cirun-openstack-gpu-large                # [linux and x86_64]

idle_timeout_minutes​

Configurable idle timeout that is either an int or None. Used for packages that don't have chatty enough builds. Currently only implemented in Travis and Circle.

idle_timeout_minutes: 60

linux​

The Linux-specific configuration options. This is largely an internal setting. Currently only:

linux:
  enabled: False

linux_aarch64​

The ARM-specific configuration options. This is largely an internal setting. Currently only:

linux_aarch64:
  enabled: False

linux_ppc64le​

The PPC-specific configuration options. This is largely an internal setting. Currently only:

linux_ppc64le:
  enabled: False

noarch_platforms​

Platforms on which to build noarch packages. The preferred default is a single build on linux_64.

noarch_platforms: linux_64

To build on multiple platforms, e.g. for simple packages with platform-specific dependencies, provide a list.

noarch_platforms:
  - linux_64
  - win_64

os_version​

This key is used to set the OS versions for linux_* platforms. Valid entries map a linux platform and arch to either cos6 or cos7. Currently cos6 is the default for linux-64. All other linux architectures use CentOS 7. Here is an example that enables CentOS 7 on linux-64 builds

os_version:
  linux_64: cos7

osx​

The macOSX-specific configuration options. This is largely an internal setting. Currently only:

osx:
  enabled: False

provider​

warning

Feedstocks in conda-forge do not allow using self-hosted runners of other GitHub organisations.

The provider field is a mapping from build platform (not target platform) to CI service. It determines which service handles each build platform. The following are available as build platforms:

  • linux_64
  • osx_64
  • win_64
  • linux_aarch64
  • linux_ppc64le

The following CI services are available:

  • azure
  • circle
  • travis
  • appveyor
  • github_actions
  • None or False to disable a build platform.
  • default to choose an appropriate CI (only if available)
  • native to choose an appropriate CI for native compiling (only if available)
  • emulated to choose an appropriate CI for compiling inside an emulation of the target platform (only if available)

Note that github_actions is not available for the conda-forge github organization except for self-hosted runs to avoid a denial of service due to other critical infrastructure running on Github actions. Other github organizations may use github_actions as a CI provider.

For example, switching linux_64 & osx_64 to build on Travis CI, with win_64 on Appveyor:

provider:
  linux_64: travis
  osx_64: travis
  win_64: appveyor

Currently, x86_64 platforms are enabled, but other build platforms are disabled by default. i.e. an empty provider entry is equivalent to the following:

provider:
  linux_64: azure
  osx_64: azure
  win_64: azure
  linux_ppc64le: None
  linux_aarch64: None

To enable linux_ppc64le and linux_aarch64 add the following:

provider:
  linux_ppc64le: default
  linux_aarch64: default

If a desired build platform is not available with a selected provider (either natively or with emulation), the build will be disabled. Use the build_platform field to manually specify cross-compilation when no providers offer a desired build platform.

recipe_dir​

The relative path to the recipe directory. The default is:

recipe_dir: recipe

remote_ci_setup​

This option can be used to override the default conda-forge-ci-setup package. Can be given with ${url or channel_alias}::package_name, defaults to conda-forge channel_alias if no prefix is given.

remote_ci_setup: "conda-forge-ci-setup=3"

shellcheck​

Shell scripts used for builds or activation scripts can be linted with shellcheck. This is not enabled by default, but can be enabled like so:

shellcheck:
  enabled: True

skip_render​

This option specifies a list of files which conda smithy will skip rendering. The possible values can be a subset of .gitignore, .gitattributes, README.md, LICENSE.txt. The default value is an empty list [ ], i.e. all these four files will be generated by conda smithy. For example, if you want to customize .gitignore and LICENSE.txt files on your own, you should have the following configuration.

skip_render:
  - .gitignore
  - LICENSE.txt

templates​

This is mostly an internal field for specifying where templates files live. You shouldn't need it.

test_on_native_only​

This is used for disabling testing for cross compiling. Default is false

test_on_native_only: True
note

This has been deprecated in favor of the test top-level field. It is now mapped to test: native_and_emulated.

test​

This is used to configure on which platforms a recipe is tested. Default is all.

test: native_and_emulated

Will do testing only if the platform is native or if there is an emulator.

test: native

Will do testing only if the platform is native.

travis​

The top-level travis key specifies configurations for the Travis CI service. This is usually read-only and should not normally be manually modified. Tools like conda-smithy may modify this, as needed.

upload_on_branch​

This parameter restricts uploading access on work from certain branches of the same repo. Only the branch listed in upload_on_branch will trigger uploading of packages to the target channel. The default is to skip this check if the key upload_on_branch is not in conda-forge.yml. To restrict uploads to the main branch:

upload_on_branch: main

win​

The Windows-specific configuration options. This is largely an internal setting. Currently only:

win:
  enabled: False