[hf CLI] check for updates and notify user

Author: Wauplin

.github/workflows/check-installers.yml

@@ -36,6 +36,9 @@ jobs:
 
           export PATH="$BIN_DIR:$PATH"
 
+      - name: Check installation
+        shell: bash
+        run: |
           HF_VERSION_PATH="$HF_TEST_ROOT/hf-version.txt"
           hf version | tee "$HF_VERSION_PATH"
           if ! grep -Eq 'huggingface_hub version: [0-9]+(\.[0-9]+){1,2}' "$HF_VERSION_PATH"; then
@@ -48,13 +51,22 @@ jobs:
 
           rm -rf "$HF_TEST_ROOT"
 
+      - name: Check installation method
+        shell: bash
+        run: |
+          hf env
+          if ! hf env | grep -Fq 'Installation method: hf_installer'; then
+            echo "❌ Error: not installed with hf_installer."
+            exit 1
+          fi
+
   windows-installer:
     runs-on: windows-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Run installer 
+      - name: Run installer
         shell: pwsh
         run: |
           $hfTestRoot = Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString())
@@ -86,3 +98,12 @@ jobs:
           Remove-Item Env:NO_COLOR
 
           Remove-Item -Path $hfTestRoot -Recurse -Force
+
+      - name: Check installation method
+        shell: pwsh
+        run: |
+          hf env
+          if (-not (hf env | Select-String -SimpleMatch 'Installation method: hf_installer')) {
+            Write-Error "❌ Error: not installed with hf_installer."
+            exit 1
+          }

src/huggingface_hub/cli/_cli_utils.py

@@ -13,15 +13,21 @@
 # limitations under the License.
 """Contains CLI utilities (styling, helpers)."""
 
+import importlib.metadata
 import os
+import time
 from enum import Enum
 from typing import Annotated, Optional, Union
 
 import click
 import typer
 
-from huggingface_hub import __version__
+from huggingface_hub import __version__, constants
 from huggingface_hub.hf_api import HfApi
+from huggingface_hub.utils import get_session, hf_raise_for_status, installation_method, logging
+
+
+logger = logging.get_logger()
 
 
 class ANSI:
@@ -144,3 +150,79 @@ class RepoType(str, Enum):
 
 def get_hf_api(token: Optional[str] = None) -> HfApi:
     return HfApi(token=token, library_name="hf", library_version=__version__)
+
+
+### PyPI VERSION CHECKER
+
+
+def check_cli_update() -> None:
+    """
+    Check whether a newer version of `huggingface_hub` is available on PyPI.
+
+    If a newer version is found, notify the user and suggest updating.
+    The latest PyPI version is cached locally in `$HF_HOME/pypi_latest_version` for 24 hours to prevent repeated notifications.
+    If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed.
+
+    This function is called at the entry point of the CLI.
+    """
+    try:
+        _check_cli_update()
+    except Exception:
+        # We don't want the CLI to fail on version checks, no matter the reason.
+        logger.debug("Error while checking for CLI update.", exc_info=True)
+
+
+def _check_cli_update() -> None:
+    current_version = importlib.metadata.version("huggingface_hub")
+
+    if any(tag in current_version for tag in ["a", "b", "rc", "dev"]):
+        # Don't check for pre-releases or dev versions
+        return
+
+    cached_version = _get_cached_pypi_version()
+    if cached_version is None:
+        latest_version = _get_pypi_version()
+        _cache_pypi_version(latest_version)
+    else:
+        latest_version = cached_version
+
+    if current_version != latest_version:
+        method = installation_method()
+        if method == "brew":
+            update_command = "brew upgrade huggingface-cli"
+        elif method == "hf_installer" and os.name == "nt":
+            update_command = "curl -LsSf https://hf.co/cli/install.ps1 | pwsh -"
+        elif method == "hf_installer":
+            update_command = "curl -LsSf https://hf.co/cli/install.sh | sh -"
+        else:  # unknown => likely pip
+            update_command = "pip install -U huggingface_hub"
+
+        click.echo(
+            ANSI.yellow(
+                f"A new version of huggingface_hub ({latest_version}) is available! "
+                f"You are using version {current_version}.\n"
+                f"To update, run: {ANSI.bold(update_command)}\n",
+            )
+        )
+
+
+def _get_pypi_version() -> str:
+    response = get_session().get("https://pypi.org/pypi/huggingface_hub/json", timeout=2)
+    hf_raise_for_status(response)
+    data = response.json()
+    return data["info"]["version"]
+
+
+def _get_cached_pypi_version() -> Optional[str]:
+    if os.path.exists(constants.PYPI_LATEST_VERSION_PATH):
+        mtime = os.path.getmtime(constants.PYPI_LATEST_VERSION_PATH)
+        # If the file is older than 24h, we don't use it
+        if (time.time() - mtime) < 24 * 3600:
+            with open(constants.PYPI_LATEST_VERSION_PATH, "r", encoding="utf-8") as f:
+                return f.read().strip()
+    return None
+
+
+def _cache_pypi_version(version: str) -> None:
+    with open(constants.PYPI_LATEST_VERSION_PATH, "w", encoding="utf-8") as f:
+        f.write(version)

src/huggingface_hub/cli/hf.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-from huggingface_hub.cli._cli_utils import typer_factory
+from huggingface_hub.cli._cli_utils import check_cli_update, typer_factory
 from huggingface_hub.cli.auth import auth_cli
 from huggingface_hub.cli.cache import cache_cli
 from huggingface_hub.cli.download import download
@@ -52,6 +52,7 @@
 
 def main():
     logging.set_verbosity_info()
+    check_cli_update()
     app()
 
 

src/huggingface_hub/constants.py

@@ -163,6 +163,9 @@ def _as_int(value: Optional[str]) -> Optional[int]:
 
 HF_HUB_OFFLINE = _is_true(os.environ.get("HF_HUB_OFFLINE") or os.environ.get("TRANSFORMERS_OFFLINE"))
 
+# Used to check if CLI is up-to-date
+PYPI_LATEST_VERSION_PATH = os.path.join(HF_HOME, "pypi_latest_version")
+
 # If set, log level will be set to DEBUG and all requests made to the Hub will be logged
 # as curl commands for reproducibility.
 HF_DEBUG = _is_true(os.environ.get("HF_DEBUG"))

src/huggingface_hub/utils/__init__.py

@@ -86,6 +86,7 @@
     get_tensorboard_version,
     get_tf_version,
     get_torch_version,
+    installation_method,
     is_aiohttp_available,
     is_colab_enterprise,
     is_fastai_available,

src/huggingface_hub/utils/_http.py

@@ -744,9 +744,9 @@ def _curlify(request: httpx.Request) -> str:
     flat_parts = []
     for k, v in parts:
         if k:
-            flat_parts.append(quote(k))
+            flat_parts.append(quote(str(k)))
         if v:
-            flat_parts.append(quote(v))
+            flat_parts.append(quote(str(v)))
 
     return " ".join(flat_parts)
 

src/huggingface_hub/utils/_runtime.py

@@ -19,7 +19,8 @@
 import platform
 import sys
 import warnings
-from typing import Any
+from pathlib import Path
+from typing import Any, Literal
 
 from .. import __version__, constants
 
@@ -322,6 +323,49 @@ def is_colab_enterprise() -> bool:
     return os.environ.get("VERTEX_PRODUCT") == "COLAB_ENTERPRISE"
 
 
+# Check how huggingface_hub has been installed
+
+
+def installation_method() -> Literal["brew", "hf_installer", "unknown"]:
+    """Return the installation method of the current environment.
+
+    - "hf_installer" if installed via the official installer script
+    - "brew" if installed via Homebrew
+    - "unknown" otherwise
+    """
+    if _is_brew_installation():
+        return "brew"
+    elif _is_hf_installer_installation():
+        return "hf_installer"
+    else:
+        return "unknown"
+
+
+def _is_brew_installation() -> bool:
+    """Check if running from a Homebrew installation.
+
+    Note: AI-generated by Claude.
+    """
+    exe_path = Path(sys.executable).resolve()
+    exe_str = str(exe_path)
+
+    # Check common Homebrew paths
+    # /opt/homebrew (Apple Silicon), /usr/local (Intel)
+    return "/Cellar/" in exe_str or "/opt/homebrew/" in exe_str or exe_str.startswith("/usr/local/Cellar/")
+
+
+def _is_hf_installer_installation() -> bool:
+    """Return `True` if the current environment was set up via the official hf installer script.
+
+    i.e. using one of
+        curl -LsSf https://hf.co/cli/install.sh | sh
+        curl -LsSf https://hf.co/cli/install.ps1 | pwsh -
+    """
+    venv = sys.prefix  # points to venv root if active
+    marker = Path(venv) / ".hf_installer_marker"
+    return marker.exists()
+
+
 def dump_environment_info() -> dict[str, Any]:
     """Dump information about the machine to help debugging issues.
 
@@ -366,6 +410,9 @@ def dump_environment_info() -> dict[str, Any]:
     except Exception:
         pass
 
+    # How huggingface_hub has been installed?
+    info["Installation method"] = installation_method()
+
     # Installed dependencies
     info["Torch"] = get_torch_version()
     info["httpx"] = get_httpx_version()

utils/installers/install.ps1

@@ -223,6 +223,10 @@ function New-VirtualEnvironment {
     }
     if (-not $?) { throw "Failed to create virtual environment" }
 
+    # Mark this installation as installer-managed
+    $markerFile = Join-Path $VENV_DIR ".hf_installer_marker"
+    New-Item -Path $markerFile -ItemType File -Force | Out-Null
+
     # Use the venv's python -m pip for deterministic upgrades
     $script:VenvPython = Join-Path $SCRIPTS_DIR "python.exe"
     Write-Log "Upgrading pip..."

utils/installers/install.sh

@@ -180,7 +180,7 @@ detect_os() {
 
 # Install Python if not available
 python_version_supported() {
-    "$1" - <<'PY' >/dev/null 2>&1
+    "$1" <<'PY' >/dev/null 2>&1
 import sys
 sys.exit(0 if sys.version_info >= (3, 9) else 1)
 PY
@@ -268,6 +268,9 @@ create_venv() {
 
     run_command "Failed to create virtual environment at $VENV_DIR" "$PYTHON_CMD" -m venv "$VENV_DIR"
 
+    # Mark this installation as installer-managed
+    touch "$VENV_DIR/.hf_installer_marker"
+
     # Use the venv python for pip management
     log_info "Upgrading pip..."
     run_command "Failed to upgrade pip" "$VENV_DIR/bin/python" -m pip install --upgrade pip