python-tests.yml

name: Python tests

on:
  push:
    branches:
      - main
      - ci_*
    paths-ignore:
      - "docs/**"
  pull_request:
    types: [opened, synchronize, reopened]
    paths-ignore:
      - "docs/**"

# Cancel superseded runs: a new push to a PR makes the previous run useless.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check-imports:
    # Catch missing dependencies: install only base requirements and verify all public imports work.
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: "3.14"
      - name: Install base dependencies only
        run: |
          pip install --upgrade uv
          uv venv
          uv pip install .
      - name: Check imports
        run: |
          source .venv/bin/activate
          python utils/check_imports.py

  build-ubuntu:
    runs-on:
      group: aws-general-8-plus
    # A healthy full-suite job takes ~20min. Anything much longer means something is stuck: fail fast instead of
    # burning a runner until GitHub's 6h limit.
    timeout-minutes: 45
    env:
      UV_HTTP_TIMEOUT: 600 # max 10min to install deps

    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.14"]
        test_name: ["no hf_xet", "Inference only", "with hf_xet"]
        include:
          - python-version: "3.10" # test torch~=1.11 on python 3.10 only.
            test_name: "Python 3.10, torch_1.11"
          - python-version: "3.12" # test torch latest on python 3.12 only.
            test_name: "torch_latest"
          - python-version: "3.13" # gradio not supported on 3.14 -> test it on 3.13
            test_name: "gradio"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      # Setup venv
      # TODO: revisit when https://github.com/astral-sh/uv/issues/1526 is addressed.
      - name: Setup venv + uv
        run: |
          pip install --upgrade uv
          uv venv

      # Install dependencies
      - name: Install dependencies
        run: |
          uv pip install "huggingface_hub[testing] @ ."

          case "${{ matrix.test_name }}" in

            "no hf_xet" | "Inference only")
              sudo apt update
              sudo apt install -y libsndfile1-dev
              ;;

            gradio)
              uv pip install "huggingface_hub[gradio] @ ."
            ;;

            torch_latest)
              uv pip install "huggingface_hub[torch] @ ."
              uv pip install --upgrade torch
              ;;

            "Python 3.10, torch_1.11")
              uv pip install "huggingface_hub[torch] @ ."
              uv pip install torch~=1.11
              ;;

          esac

          # Xet policy (see `xet_mode` fixture in tests/conftest.py):
          # - "with hf_xet" job: hf_xet installed (comes with `huggingface_hub[testing]`). Runs `-m 'not no_xet'` => `xet` tests + unmarked tests with Xet.
          # - all other jobs: hf_xet uninstalled. Run `-m 'not xet'` => `no_xet` tests + unmarked tests without Xet.
          # Unmarked tests therefore run both with and without Xet and must work regardless.
          if [[ "${{ matrix.test_name }}" != "with hf_xet" ]]; then
            uv pip uninstall hf_xet
          fi

      # Run tests
      - name: Run tests
        working-directory: ./src # For code coverage to work
        run: |
          source ../.venv/bin/activate
          PYTEST="python -m pytest --cov=./huggingface_hub --cov-report=xml:../coverage.xml --vcr-record=none --reruns 8 --reruns-delay 2 --only-rerun '(OSError|FileNotFoundError|Timeout|HTTPError.*409|HTTPError.*502|HTTPError.*504)'"

          case "${{ matrix.test_name }}" in

            "Inference only")
              # Run inference tests concurrently
              PYTEST="$PYTEST ../tests -m 'inference' -n 4"
              echo $PYTEST
              eval $PYTEST
            ;;

            "no hf_xet")
              PYTEST="$PYTEST ../tests -m 'not xet and not inference' -n 4"
              echo $PYTEST
              eval $PYTEST
            ;;

            gradio)
              eval "$PYTEST ../tests/test_webhooks_server.py"
            ;;

            "Python 3.10, torch_1.11" | torch_latest)
            eval "$PYTEST ../tests/test_hub_mixin*"
            eval "$PYTEST ../tests/test_serialization.py"
            ;;

            "with hf_xet")
              # `xet` tests + unmarked tests, all with hf_xet installed.
              # Inference tests are excluded: they have their own job and don't depend on Xet.
              PYTEST="$PYTEST ../tests -m 'not no_xet and not inference' -n 4"
              echo $PYTEST
              eval $PYTEST
            ;;

          esac

      # Upload code coverage
      - name: Upload coverage reports to Codecov with GitHub Action
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7.0.0
        with:
          files: ./coverage.xml
          verbose: true

  build-windows:
    # (almost) Duplicate config compared to `build-ubuntu` but running on Windows.
    # Please make sure to keep it updated as well.
    runs-on: windows-latest
    timeout-minutes: 30
    env:
      DISABLE_SYMLINKS_IN_WINDOWS_TESTS: 1
      UV_HTTP_TIMEOUT: 600 # max 10min to install deps
      GIT_CLONE_PROTECTION_ACTIVE: false # See https://github.com/git-lfs/git-lfs/issues/5754
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.14"]
        test_name: ["no hf_xet", "with hf_xet"]

    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      # Setup venv
      # TODO: revisit when https://github.com/astral-sh/uv/issues/1526 is addressed.
      - name: Setup venv + uv
        run: |
          pip install --upgrade uv
          uv venv

      # Install dependencies
      - name: Install dependencies
        run: |
          uv pip install "huggingface_hub[testing] @ ."

          # Xet policy (see `xet_mode` fixture in tests/conftest.py):
          # - "with hf_xet" job: hf_xet installed (comes with `huggingface_hub[testing]`). Runs `-m 'not no_xet'` => `xet` tests + unmarked tests with Xet.
          # - all other jobs: hf_xet uninstalled. Run `-m 'not xet'` => `no_xet` tests + unmarked tests without Xet.
          # Unmarked tests therefore run both with and without Xet and must work regardless.
          if ("${{ matrix.test_name }}" -ne "with hf_xet") {
            uv pip uninstall hf_xet
          }

      # Run tests
      - name: Run tests
        working-directory: ./src # For code coverage to work
        run: |
          ..\.venv\Scripts\activate
          $PYTEST_ARGS = @(
            "-m", "pytest",
            "-n", "4",
            "--cov=./huggingface_hub",
            "--cov-report=xml:../coverage.xml",
            "--vcr-record=none",
            "--reruns", "8",
            "--reruns-delay", "2",
            "--only-rerun", "(OSError|FileNotFoundError|Timeout|HTTPError.*409|HTTPError.*502|HTTPError.*504)",
            "../tests"
          )

          switch ("${{ matrix.test_name }}") {
            "with hf_xet" {
              # `xet` tests + unmarked tests, all with hf_xet installed.
              # Inference tests already run in "no hf_xet" and don't depend on Xet.
              python $PYTEST_ARGS -m "not no_xet and not inference"
            }
            "no hf_xet" {
              python $PYTEST_ARGS -m "not xet"
            }
          }

      # Upload code coverage
      - name: Upload coverage reports to Codecov with GitHub Action
        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7.0.0
        with:
          files: ./coverage.xml
          verbose: true