How to determine registry.hf.space image name given (long) space name?

Spaces
1

If I have a space called my-org/some-name, the Docker image built from it will be located at registry.hf.space/my-org-some-name. However, if the combined my-org/some-name string is long enough, the image name in the registry will be truncated and it will have 7 hex digits appended at the end, something like: my-very-long-org-name-some-very-long-space-name-<7 hex digits>

Does anyone know how to compute the image name from the space name in this case? Presumably those hex digits are the hash of some part of the full name, but it’s not any of the obvious ones (like the SHA256 of the full name).

1 Like
2

If the Space name is too long, we users might not be able to automatically guess the domain name on our own…

You can’t deterministically compute that 7-hex suffix yourself. Hugging Face does not document the truncation/uniqueness algorithm it uses for long Space names, and it’s not part of any public/stable API. When a Space’s slug would be too long, the registry repo name is shortened and a short hash is appended for uniqueness; the exact hashing scheme is internal and subject to change. Use one of the reliable discovery methods below instead. (Hugging Face)

Background (what’s going on)

  • Normal case: <org>/<space> becomes registry.hf.space/<org>-<space> (for example, openenv/echo-env → registry.hf.space/openenv-echo-env). (Hugging Face)
  • Long names: when that combined slug gets too long for downstream systems (think DNS/Kubernetes label limits of ~63 chars per label), platforms commonly truncate and append a short hash to keep names unique. HF’s docs show how to use the Docker image but don’t publish the hashing rule; they encourage clicking the Space’s Run with Docker button to get the exact docker run command (which includes the true image path). (Kubernetes)
  • There’s no public spec or SDK method that returns “the registry repo string.” The closest you get is HfApi.get_space_runtime(...), whose raw field may include extra backend info, but HF explicitly treats it as an opaque server response, not a guaranteed schema. (Hugging Face)

Reliable ways to get the exact image name

  1. From the Space UI (fastest & most stable)
    Open the Space page and click Run with Docker. The dialog shows a complete docker run command that embeds the exact registry repo and tag. This works regardless of truncation or hashing. (Hugging Face)

  2. From Python via huggingface_hub (programmatic, best-effort)
    Query the runtime; if the backend includes image details in raw, read them there. It’s not guaranteed, but it’s the only supported API surface you can poll.

# pip install --upgrade "huggingface_hub>=0.20"
from huggingface_hub import HfApi

api = HfApi()  # use HfApi(token="hf_xxx") for private Spaces
runtime = api.get_space_runtime("my-org/some-very-long-space-name")
print(runtime)          # documented fields
print(runtime.raw)      # may contain extra backend fields (not stable)
# Docs:
# - Space runtime class: https://huggingface.co/docs/huggingface_hub/en/package_reference/space_runtime
# - Manage your Space:   https://huggingface.co/docs/huggingface_hub/en/guides/manage-spaces

(Hugging Face)

  1. Probe the registry using the Docker/OCI Distribution API (works even if the name is hashed—once you know it)
    Registries implement the Distribution (Docker Registry v2 / OCI) API. You can test if a repo:tag exists with a HEAD /v2/<name>/manifests/<tag> (or list tags with /v2/<name>/tags/list) using basic auth (HF username + token). This is the canonical way to check image existence. (GitHub Distribution)
# 1) Log in so docker can pull later
docker login registry.hf.space
# username: <your HF username>
# password: <your HF access token>

# 2) Probe a candidate repo+tag with the Distribution API
# (replace USER and TOKEN, and choose the Accept for OCI/Docker manifests)
curl -sI -u USER:HF_TOKEN \
  -H 'Accept: application/vnd.oci.image.manifest.v1+json' \
  https://huggingface.co/proxy/registry.hf.space/v2/my-org-some-very-long-space-name-<7hex>/manifests/latest
# 200 = exists, 404 = not found, 401 = auth issue.
# Spec: https://distribution.github.io/distribution/spec/api/

(GitHub Distribution)

Practical workflow you can adopt

  1. Prefer the Run with Docker button to copy the exact image path; it’s the source of truth. (Hugging Face)
  2. If you must script it, call get_space_runtime(...) and inspect runtime.raw. Treat it as best-effort. (Hugging Face)
  3. As a final check before pulling, issue a Distribution-API HEAD against the repo:tag you plan to use. This catches typos and mismatches early. (GitHub Distribution)

Why the 7-hex suffix exists (context)

Container names frequently need to satisfy DNS/Kubernetes constraints—most notably 63-character label limits. To preserve uniqueness after truncation, platforms append short hashes. HF does not publish their exact hashing recipe, so reverse-engineering it is brittle and likely to break. Use the UI/API instead. (Kubernetes)

Notes and gotchas

  • The registry domain you’ll see in logs may vary (registry.hf.space in public docs; you may encounter internal hostnames in error logs). Always use the public domain shown by the Space UI. (Hugging Face)
  • Some registry endpoints (like _catalog) are commonly disabled for security; don’t rely on them to “discover” repos. Stick to known repo names and benign HEAD checks. (GitHub Distribution)
  • Forum reports confirm that mapping “by hand” is fragile and that outages/auth gating can also cause false negatives when probing images. Verify auth and tags. (Hugging Face Forums)

Minimal examples you can reuse

Discover via UI (copy/paste):

  • Go to Space → Run with Docker → copy docker run ... registry.hf.space/<repo>:<tag>. (Hugging Face)

Probe a candidate (shell):

# Docs for the API used: https://distribution.github.io/distribution/spec/api/
curl -sI -u USER:HF_TOKEN \
  -H 'Accept: application/vnd.oci.image.manifest.v1+json' \
  https://huggingface.co/proxy/registry.hf.space/v2/<repo>/manifests/<tag>

(GitHub Distribution)

Programmatic (Python):

# Docs:
# - Space runtime reference: https://huggingface.co/docs/huggingface_hub/en/package_reference/space_runtime
# - Manage Spaces via API:  https://huggingface.co/docs/huggingface_hub/en/guides/manage-spaces
from huggingface_hub import HfApi
api = HfApi(token="hf_...")  # optional if public
rt = api.get_space_runtime("my-org/my-very-long-space")
print(rt.raw)  # may include backend details; not guaranteed stable

(Hugging Face)

Curated references

Official docs (how to run & manage)

  • Run with Docker (shows the exact command in the UI). (Hugging Face)
  • Manage your Space (Python examples); SpaceRuntime docs (note the raw field). (Hugging Face)

Distribution / Registry API (how to verify repos & tags)

Context on name-length constraints

  • Kubernetes object naming & DNS label limits (why truncation happens in many systems). (Kubernetes)

Community threads (behavior in the wild)

  • Example “Run with Docker” mappings and registry usage in practice. (Hugging Face)
  • Outage/auth issues that can look like “name not found.” (Hugging Face Forums)
3

Thank you so much for the thorough response, @John6666 !

1 Like
4

This topic was automatically closed 12 hours after the last reply. New replies are no longer allowed.