# Imagens de Container

As Imagens de Container são um tipo de repositório no Hugging Face Hub para imagens Docker e outras imagens [OCI](https://opencontainers.org/). O registro de containers do Hugging Face, `cr.hf.co`, armazena as imagens no backend de armazenamento [Xet](./xet/index). Envie e baixe-as com [`hf image`](#pushing-and-pulling-with-hf-image), o cliente recomendado; clientes padrão, como Docker, Podman, crane, skopeo, ORAS e Helm, também funcionam.

> [!NOTE]
> As Imagens de Container estão em beta privado: [entre em contato conosco](https://huggingface.co/contact/sales) para ativá-las para sua organização.

## Criando um Repositório

Acesse [huggingface.co/new-container](https://huggingface.co/new-container) e escolha a organização, um nome e a visibilidade. Ou use a 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}'
```

Crie o repositório antes de fazer o push: um push para um repositório inexistente falha com `NAME_UNKNOWN`. A página dele, `https://huggingface.co/containers/my-org/my-app`, lista as tags. Quem pode fazer pull e push segue a visibilidade do repositório e o papel de cada membro na organização.

## Enviando e baixando com `hf image`

[`hf image`](https://github.com/huggingface/hf-image), uma extensão do CLI `hf`, transfere apenas as partes de cada camada que foram alteradas desde a versão anterior, resultando em uma experiência mais rápida em comparação com outros 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
```

Ele usa seu [User Access Token](./security-tokens) do Hugging Face (`read` para puxar, `write` para enviar) e requer o Docker com o [containerd image store](https://docs.docker.com/engine/storage/containerd/). As imagens enviadas com `hf image` podem ser puxadas por qualquer cliente.

Como `hf image` armazena as camadas sem compressão, as imagens que ele envia recebem digests diferentes dos obtidos com `docker push`. Para manter os digests do `docker push`, por exemplo para assinaturas ou implantações fixadas por digest, use `hf image push --preserve-digests`. Esse processo é mais lento: as camadas alteradas são então enviadas e baixadas por completo, assim como no `docker push`.

## Usando Docker e outros clientes OCI

Embora recomendemos o uso de `hf image` (veja a seção anterior) para aproveitar plenamente o [backend Xet](./xet/index), você também pode interagir com o registro por meio de qualquer cliente OCI.

Faça login com seu nome de usuário do Hugging Face e um [User Access Token](./security-tokens) como senha: `read` para puxar, `write` para enviar. Imagens públicas podem ser puxadas sem fazer login.

```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
```

Outros clientes OCI funcionam da mesma forma. O Helm adiciona o nome do gráfico à URL: `helm push mychart-0.1.0.tgz oci://cr.hf.co/my-org` envia para `my-org/mychart`, que deve existir previamente.

## Excluindo Imagens

No Hub, remova uma tag usando **Excluir esta tag** no menu, na página da imagem ou da tag. Com [`hf image`](#pushing-and-pulling-with-hf-image), remova as tags de uma imagem e, em seguida, exclua-a pelo 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>
```

Se algo ainda referencia a imagem, como outra tag, a exclusão é recusada e lista o que deve ser removido primeiro. A exclusão de uma imagem multi-arch também exclui suas imagens de plataforma.

## Coleta de Lixo

O registro exclui as imagens que nenhuma tag aponta mais, diretamente ou por meio de uma imagem multi-arquitetura, como a `latest` anterior após um novo push. Ele também exclui as camadas que nenhuma imagem restante utiliza. Para continuar puxando uma imagem por digest, mantenha uma tag nela.

## Limites

- Os nomes de imagem são `cr.hf.co/<namespace>/<name>`, em minúsculas.
- Camadas de até 100 GB, manifests de até 4 MiB.
- Listas de tags podem levar alguns segundos para exibir uma nova tag.