setup-miniconda

Conda activation behavior varies significantly depending on the shell used in GitHub Actions:

• sh: Conda activation does not work correctly in sh. Use bash instead.
• bash: Standard GitHub Actions bash steps run with --noprofile --norc, which ignores conda init changes in ~/.bashrc. To ensure activation works, use shell: bash -el {0} or set it as a job default.
• sh (alternative): If you must use sh, use shell: sh -l {0} to ensure profile files are loaded.
• cmd (Windows): cmd shells do not run Autorun commands. To ensure activation works, use shell: cmd /C call {0}.

General Constraints:

• use-only-tar-bz2: Must be set to true for caching to work.
• Channel Conflicts: If providing channels via the action, ensure they do not conflict with channels defined in your environment.yaml, as this can cause solver failures or extremely long install times.

You can cache entire conda environments to avoid re-solving and re-installing dependencies.

Workflow Pattern:

1. Initial Setup: Run setup-miniconda without an environment-file to set up the base Miniconda/Miniforge installation.
2. Cache Check: Use actions/cache with a key that includes a hash of your environment file (e.g., environment.yml) and a timestamp/date to ensure freshness.
3. Environment Update: If a cache hit is not found, use mamba env update or conda env update to build the environment from your file.

Warning: Hashing an environment.yml file is not the same as hashing a resolved environment. Because packages in channels change over time, the same YAML file can result in different environments. To ensure absolute reproducibility, use a resolved environment file (e.g., from conda list --explicit).

- name: Setup Miniforge
  uses: conda-incubator/setup-miniconda@v4
  with:
    miniforge-version: latest
    activate-environment: anaconda-client-env

- name: Get Date
  id: get-date
  run: echo "today=$(/bin/date -u '+%Y%m%d')" >> $GITHUB_OUTPUT
  shell: bash

- name: Cache Conda env
  uses: actions/cache@v5
  with:
    path: ${{ env.CONDA }}/envs
    key: conda-${{ runner.os }}--${{ runner.arch }}--${{ steps.get-date.outputs.today }}-${{ hashFiles('etc/example-environment-caching.yml') }}-${{ env.CACHE_NUMBER }}
  env:
    CACHE_NUMBER: 0
  id: cache

- name: Update environment
  run: |
    mamba env update -n anaconda-client-env -f etc/example-environment-caching.yml
  if: steps.cache.outputs.cache-hit != 'true'

To speed up workflows, you can cache conda packages using actions/cache. By default, conda uses ~/conda_pkgs_dir as the package directory.

Important Requirements:

• You must set use-only-tar-bz2: true in the setup-miniconda configuration for caching to work properly.
• If you change the package directory using the pkgs-dirs option, ensure your cache path matches that directory.
• If using pip within your conda environment, those dependencies are not included in the conda package cache and must be cached separately.

On Windows runners, using the D: drive for package directories and enabling enableCrossOsArchive in the cache configuration can improve decompression speeds.

jobs:
  caching-example:
    name: Caching
    runs-on: "ubuntu-latest"
    steps:
      - uses: actions/checkout@v6
      - name: Cache conda
        uses: actions/cache@v5
        env:
          CACHE_NUMBER: 0
        with:
          path: ~/conda_pkgs_dir
          key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{ hashFiles('etc/example-environment.yml') }}
      - uses: conda-incubator/setup-miniconda@v4
        with:
          activate-environment: anaconda-client-env
          channel-priority: strict
          environment-file: etc/example-environment.yml
          use-only-tar-bz2: true # IMPORTANT: This needs to be set for caching to work properly!

If your environment (e.g., corporate self-hosted runners) prevents modifications to ~/.profile or ~/.bashrc, you must prevent setup-miniconda from attempting to modify these files and manually source conda in your steps.

Configuration:

• Set run-init: "false"
• Set remove-profiles: "false"

Usage: Manually source the conda profile script in your shell steps using source "$CONDA/etc/profile.d/conda.sh" before calling conda activate.

jobs:
  restricted-env:
    name: Restricted environment
    runs-on: "ubuntu-latest"
    steps:
      - uses: actions/checkout@v6
      - uses: conda-incubator/setup-miniconda@v4
        with:
          activate-environment: myenv
          environment-file: environment.yml
          remove-profiles: "false"
          run-init: "false"
      - name: Run with conda
        shell: bash
        run: |
          source "$CONDA/etc/profile.d/conda.sh"
          conda activate myenv
          python my_script.py