DOCSEARCHbyAlgolia
Submit Docs

huggingface_hub

repository·main·Indexed 26 days ago

https://github.com/huggingface/huggingface_hub

The official CLI and Python client for interacting with the Hugging Face Hub. It enables developers and AI agents to download, upload, and manage repositories, run inference, and execute jobs on Hugging Face infrastructure. Key features include the hf CLI for terminal operations, the HfApi class for programmatic repository management, and utility functions like hf_hub_download and snapshot_download for efficient file and repository retrieval.

Tokens
117.6K
Snippets
385
Records
706
Agent score
85%

What's inside huggingface_hub

  1. Overview of the huggingface_hub library

    main

    The huggingface_hub Python library allows you to interact programmatically with the Hugging Face Hub. You can use it to:

    • Find pre-trained models and datasets for your projects.
    • Experience machine learning applications hosted on the platform.
    • Create, share, and manage your own models and datasets.
    • Download files from the Hub.
    • Create repositories.
    • Upload files to the Hub.
    • Access Inference APIs.
    • Manage repositories and participate in discussions.

  3. Explore huggingface_hub operation guides

    main

    The huggingface_hub library provides various guides to help you interact with the Hugging Face Hub. Key capabilities include:

    • Repository Management: Create, configure, and interact with repositories on the Hub.
    • File Operations: Download files or entire repositories, and upload files or folders (including making changes to existing repositories).
    • Searching: Efficiently search through models, datasets, and Spaces.
    • HfFileSystem: Interact with the Hub using a convenient interface that mimics the Python file system API.
    • Inference: Use accelerated Inference APIs to perform predictions.
    • Community Interaction: Engage with the community via discussions and pull requests.
    • Collections: Programmatically build and manage collections.
    • Cache Management: Understand and utilize the caching system.
    • Model Cards: Create and share model cards.
    • Space Management: Manage hardware and configurations for your Spaces.
    • Integrations: Learn how to integrate libraries with the Hub.
    • Webhooks: Create a server to receive Webhooks and deploy it as a Space.

  5. Integrate an ML framework with the Hugging Face Hub

    main

    To integrate a machine learning library with the Hugging Face Hub, you can implement three main patterns:

    1. Push to Hub: Implement a method (commonly named push_to_hub()) to upload model weights, model cards (README.md), training logs, and other relevant data.
    2. Download from Hub: Implement a method (commonly named from_pretrained() or load_from_hub()) to download configuration/weights and load the model into memory.
    3. Widgets: Set up a widget on the model's landing page to allow users to test the model directly in the browser.

    For deep integration involving Inference APIs and Widgets, refer to the official Inference and Widgets guide.

  7. Understand the file-based cache structure

    main

    The cache is organized by repository type (models, datasets, spaces) and uses a specific internal structure to enable file sharing across revisions and avoid redundant downloads:

    • refs/: Contains files indicating the latest revision (e.g., a file named main containing the current commit ID).
    • blobs/: Contains the actual downloaded files, named by their content hash.
    • snapshots/: Contains folders for each known revision. Inside these folders, files are symlinks pointing to the corresponding files in the blobs/ directory.
    • trees/: Caches JSON files representing the file list of a repository at a specific commit (path, size, and hash). This allows snapshot_download and hf_hub_download to skip per-file network calls if the commit is already cached.
    • .no_exist/: (Advanced) Tracks files that were attempted to be downloaded but do not exist on the Hub, preventing repeated failed HTTP calls.

  8. Run inference using InferenceClient

    main

    The InferenceClient provides a unified Python interface to run inference across multiple services:

    1. Inference Providers: Serverless access to models via partners (e.g., Replicate, Together AI).
    2. Inference Endpoints: Dedicated, managed infrastructure for production deployment.
    3. Local Endpoints: Connect to local servers like llama.cpp, Ollama, vLLM, LiteLLM, or TGI that provide an OpenAI-compatible API.

    For text-to-image tasks, the client returns a PIL.Image object. For chat completion, it returns a ChatCompletionOutput object following the OpenAI specification.

  9. Manage Hugging Face buckets with `hf buckets`

    main
    Use the hf buckets command to manage S3-like object storage containers (buckets) on the Hugging Face Hub. Buckets are designed for large-scale, mutable storage like training checkpoints and logs, using content-addressable deduplication via the Xet backend. Unlike repositories, buckets do not use git-based version control.

  10. Understand the Sandbox architecture

    main

    Sandboxes in huggingface_hub are not a dedicated service but are implemented as HF Jobs (Virtual Machines). Each sandbox runs a small, static binary called sbx-server that communicates via HTTP on port 49983.

    Key architectural details:

    • Infrastructure: Sandboxes inherit the billing, hardware flavors (including GPUs), and namespace permissions of HF Jobs.
    • Server Implementation: The sbx-server is a ~640KB static musl build with no runtime dependencies, designed to run in any x86_64 Linux image. It uses a hand-rolled HTTP/1.1 implementation to support live output streaming via NDJSON.
    • Bootstrapping: At startup, the Job fetches the binary via wget or curl. If neither is available, it falls back to copying the binary from the Job's mounted Hub repo volume.
    • Port: The server listens on port 49983 to avoid conflicts with common development ports.

  12. Quickstart with Sandboxes

    main

    A sandbox is an isolated cloud machine for running code (untrusted, AI-generated, or reproducible builds) via Python or CLI. You can use Sandbox.create() to spin up a dedicated VM or SandboxPool for many cheap CPU-only sandboxes. Any Docker image with /bin/sh is supported.

    from huggingface_hub import Sandbox

# Create a dedicated sandbox (ready in ~6s)
with Sandbox.create() as sbx:
    # Run a command and get the result
    result = sbx.run("python -c 'print(40 + 2)'")
    print(result.stdout)