# Imágenes de contenedor

Las imágenes de contenedor son un tipo de repositorio en el Hugging Face Hub para imágenes de Docker y otras imágenes [OCI](https://opencontainers.org/). El registro de contenedores de Hugging Face, `cr.hf.co`, almacena las imágenes en el backend de almacenamiento [Xet](./xet/index). Empújalas y extráelas con [`hf image`](#pushing-and-pulling-with-hf-image), el cliente recomendado; también funcionan los clientes estándar como Docker, Podman, crane, skopeo, ORAS y Helm.

> [!NOTE]
> Las imágenes de contenedor están en beta privada: [contáctanos](https://huggingface.co/contact/sales) para habilitarlas en tu organización.

## Creación de un repositorio

Ve a [huggingface.co/new-container](https://huggingface.co/new-container) y elige la organización, un nombre y la visibilidad. O usa la API:

```bash
curl -X POST https://huggingface.co/api/containers/my-org/my-app \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"private": true}'
```

Crea el repositorio antes de hacer push: un push a uno que no existe falla con `NAME_UNKNOWN`. Su página, `https://huggingface.co/containers/my-org/my-app`, lista sus tags. Quién puede hacer pull y push sigue la visibilidad del repositorio y el rol de cada miembro en la organización.

## Subir y descargar con `hf image`

[`hf image`](https://github.com/huggingface/hf-image), una extensión de la CLI `hf`, solo transfiere las partes de cada capa que cambiaron desde la versión anterior, lo que resulta en una experiencia más rápida en comparación con otros clientes OCI.

```bash
hf extensions install hf-image
hf auth login                                   # or set HF_TOKEN
hf image build -t cr.hf.co/my-org/my-app:v2 .   # optional: docker build works too
hf image push cr.hf.co/my-org/my-app:v2
hf image pull cr.hf.co/my-org/my-app:v2
```

Utiliza tu [User Access Token](./security-tokens) de Hugging Face (`read` para extraer, `write` para enviar) y requiere Docker con el [containerd image store](https://docs.docker.com/engine/storage/containerd/). Las imágenes enviadas con `hf image` pueden ser extraídas por cualquier cliente.

Como `hf image` almacena las capas sin comprimir, las imágenes que se envían obtienen sumas de verificación diferentes que con `docker push`. Para mantener las sumas de verificación de `docker push`, por ejemplo para firmas o despliegues fijados por suma de verificación, use `hf image push --preserve-digests`. Es más lento: las capas modificadas se envían y descargan por completo, como con `docker push`.

## Uso de Docker y otros clientes OCI

Aunque recomendamos usar `hf image` (ver la sección anterior) para aprovechar al máximo el [backend Xet](./xet/index), también puedes interactuar con el registro a través de cualquier cliente OCI.

Inicie sesión con su nombre de usuario de Hugging Face y un [User Access Token](./security-tokens) como contraseña: `read` para extraer, `write` para enviar. Las imágenes públicas se pueden extraer sin iniciar sesión.

```bash
echo $HF_TOKEN | docker login cr.hf.co -u <username> --password-stdin
docker tag my-app cr.hf.co/my-org/my-app:v1
docker push cr.hf.co/my-org/my-app:v1
docker pull cr.hf.co/my-org/my-app:v1
```

Otros clientes de OCI funcionan de la misma manera. Helm añade el nombre del gráfico a la URL: `helm push mychart-0.1.0.tgz oci://cr.hf.co/my-org` realiza el push a `my-org/mychart`, que debe existir previamente.

## Eliminar imágenes

En el Hub, elimina una etiqueta usando **Eliminar esta etiqueta** en su menú, en la página de la imagen o de la etiqueta. Con [`hf image`](#pushing-and-pulling-with-hf-image), elimina las etiquetas de una imagen y luego elimínala por su digest:

```bash
hf image untag cr.hf.co/my-org/my-app:v1                # prints the image's digest
hf image delete cr.hf.co/my-org/my-app@sha256:<digest>
```

Si algo sigue haciendo referencia a la imagen, como otra etiqueta, la eliminación se rechaza y se enumeran los elementos que deben eliminarse primero. Eliminar una imagen multi-arch también elimina sus imágenes de plataforma.

## Recopilación de basura

El registro elimina las imágenes a las que ya no apunta ninguna etiqueta, ya sea directamente o a través de una imagen multiarquitectura, como la anterior `latest` después de un nuevo push. También elimina las capas que ninguna imagen restante utiliza. Para seguir extrayendo una imagen por su digest, mantén una etiqueta en ella.

## Limitaciones

- Los nombres de imagen son `cr.hf.co/<namespace>/<name>`, en minúsculas.
- Capas de hasta 100 GB, manifiestos de hasta 4 MiB.
- Las listas de etiquetas pueden tardar unos segundos en mostrar una etiqueta nueva.