Hugging Face Spaces Utilities (Legacy)

0.48.2 · maintenance · verified Tue Apr 14

The `spaces` library (version 0.48.2) provides utilities for interacting with Hugging Face Spaces. It largely acts as a thin wrapper around the `huggingface_hub` library, which provides the core API for managing Spaces. As of late 2023, its development appears stalled, with most new Spaces features and ongoing maintenance occurring directly within `huggingface_hub`.

Warnings

gotcha The `spaces` library (version 0.48.2) is a distinct PyPI package from `huggingface_hub`. While `spaces` leverages `huggingface_hub` internally, its development has largely stalled. New features for Hugging Face Spaces management are exclusively added to `huggingface_hub` (e.g., `v1.9.0` introduced Spaces Volumes).
Fix: For up-to-date and complete Spaces API functionality, install and use `huggingface_hub` directly (`pip install huggingface_hub`), referring to its documentation.
deprecated The `spaces` library's APIs for interaction with Hugging Face Spaces have largely been superseded by more comprehensive and actively maintained functionalities within `huggingface_hub`. Using `spaces` may lead to missing modern features or encountering unpatched issues.
Fix: Transition existing code to use `huggingface_hub`'s `HfApi` and related classes (e.g., `from huggingface_hub import HfApi, Space, Volume`) for robust and future-proof Space management.
gotcha The release notes and version numbers provided in the prompt (e.g., `v1.10.x`) pertain to the `huggingface_hub` library, not the `spaces` library itself. The `spaces` library's last release was `0.48.2` (August 2023).
Fix: Consult the `huggingface_hub` changelog for recent updates related to Spaces features. Do not expect `spaces` (0.x) to contain features from `huggingface_hub` `1.x` releases.

Install

pip install spaces Install with pip

Imports

HfApi
```
from spaces import HfApi
```
While `from spaces.api import HfApi` also works, the `HfApi` symbol is directly exposed at the top level of the `spaces` package for convenience.

Quickstart

Demonstrates how to initialize the Hugging Face API client using the `spaces` library and list your Hugging Face Spaces. It highlights the use of an `HF_TOKEN` for authentication.

import os
from spaces import HfApi

# Authenticate using an environment variable
HF_TOKEN = os.environ.get("HF_TOKEN", "hf_YOUR_TOKEN_HERE")

if HF_TOKEN == "hf_YOUR_TOKEN_HERE":
    print("Please set the HF_TOKEN environment variable for authentication.")
    print("You can get one from https://huggingface.co/settings/tokens")
    exit(1)

api = HfApi(token=HF_TOKEN)

try:
    # This example lists spaces owned by the authenticated user
    # Note: For new features and active development, prefer 'huggingface_hub' directly.
    user_info = api.whoami()
    if user_info and 'name' in user_info:
        my_spaces = api.list_spaces(author=user_info['name'])
        print(f"Found {len(my_spaces)} spaces for user '{user_info['name']}':")
        for space in my_spaces:
            print(f"- {space.id} (Status: {space.runtime['stage']})")
    else:
        print("Could not retrieve user info. Check your token's permissions.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure your HF_TOKEN is valid and has appropriate permissions.")

view raw JSON →