{{tag>[docker cli image registry]}}

====== Docker Image ======
이미지 빌드 결과물과 레지스트리 전송, 로컬 캐시, archive 입출력을 다루는 ''docker image'' 관리 그룹.

===== Summary =====
  * ''docker images'' 는 사실상 ''docker image ls'' 의 축약형이다.
  * 이미지 이름은 보통 ''[REGISTRY_HOST/]REPOSITORY[:TAG]'' 형태이며, 같은 digest를 여러 tag가 가리킬 수 있다.
  * 배포 관점에서는 ''pull'', ''push'', ''tag'', ''save/load'', ''prune'' 의 차이를 명확히 구분하는 것이 중요하다.

===== Usage =====
<code bash>
docker image COMMAND
</code>

  * ''<color #c3c3c3>**docker image**</color> <color #ff7f27>ls</color> <color #22b14c>[OPTIONS]</color>''
  * ''<color #c3c3c3>**docker image**</color> <color #ff7f27>pull</color> <color #22b14c>[OPTIONS]</color> <color #7092be>NAME[:TAG|@DIGEST]</color>''
  * ''<color #c3c3c3>**docker image**</color> <color #ff7f27>push</color> <color #22b14c>[OPTIONS]</color> <color #7092be>NAME[:TAG]</color>''
  * ''<color #c3c3c3>**docker image**</color> <color #ff7f27>tag</color> <color #7092be>SOURCE_IMAGE[:TAG]</color> <color #7092be>TARGET_IMAGE[:TAG]</color>''
  * ''<color #c3c3c3>**docker image**</color> <color #ff7f27>rm</color> <color #22b14c>[OPTIONS]</color> <color #7092be>IMAGE</color> <color #7092be>[IMAGE...]</color>''

===== Command Groups =====
==== Registry Transfer ====
  * ''pull'': 레지스트리에서 로컬로 다운로드
    * 주요 옵션: ''--all-tags'', ''--platform'', ''-q''
  * ''push'': 로컬 이미지를 레지스트리로 업로드
    * 주요 옵션: ''-a'', ''--platform'', ''-q''
  * ''tag'': 같은 이미지에 새 이름이나 태그 부여

==== Local Inventory ====
  * ''ls'': 로컬 이미지 목록
    * 주요 옵션: ''-a'', ''--digests'', ''--filter'', ''--format'', ''--no-trunc'', ''-q''
  * ''inspect'': JSON 메타데이터 조회
    * 주요 옵션: ''-f''
  * ''history'': 레이어 이력 확인
    * 주요 옵션: ''--human'', ''--no-trunc'', ''-q''

==== Import and Export ====
  * ''save'': 하나 이상의 이미지를 tar archive로 저장
    * 주요 옵션: ''-o''
  * ''load'': tar archive 또는 stdin에서 이미지 복원
    * 주요 옵션: ''-i'', ''--platform'', ''-q''
  * ''import'': rootfs tarball에서 새 이미지 생성
    * 주요 옵션: ''-c'', ''-m'', ''--change''

==== Cleanup ====
  * ''rm'': 참조되지 않는 태그 또는 이미지 제거
    * 주요 옵션: ''-f'', ''--no-prune''
  * ''prune'': 미사용 이미지 정리
    * 주요 옵션: ''-a'', ''-f'', ''--filter until=...''
  * ''build'': 도움말상 ''docker image'' 아래에도 노출되지만 실제 빌드 흐름은 [[docker:builder]] 및 [[docker:buildx]] 기준으로 보는 편이 더 정확하다.

===== Examples =====
<code bash>
# 태그별 이미지 목록 확인
docker image ls --digests

# 새 registry 이름으로 재태깅 후 업로드
docker image tag myapp:latest registry.example.com/team/myapp:2026.07.06
docker image push registry.example.com/team/myapp:2026.07.06

# 이미지 백업
docker image save -o myapp.tar registry.example.com/team/myapp:2026.07.06

# 미사용 이미지 정리
docker image prune -a
</code>

===== Troubleshooting =====
  * ''push access denied'' 는 로그인 상태, repository 권한, registry 경로 오타를 먼저 확인한다.
  * ''latest'' 같은 mutable tag는 캐시 혼선을 만들 수 있다. 운영 배포에는 날짜나 버전 태그를 병행하는 편이 안전하다.
  * ''save/load'' 는 레지스트리 메타데이터 대신 tar 전달에 가깝다. 원격 호스트와 직접 공유할 때는 ''pull/push'' 쪽이 보통 낫다.

===== Compatibility =====
  * ''docker pull'', ''docker push'', ''docker rmi'', ''docker images'' 축약형이 널리 쓰인다.
  * multi-platform manifest 자체는 [[docker:manifest]] 또는 [[docker:buildx]] 에서 더 직접적으로 다룬다.

===== Help =====
+++ docker image --help |
<code text>
Usage:  docker image COMMAND

Manage images

Commands:
  build       Build an image from a Dockerfile
  history     Show the history of an image
  import      Import the contents from a tarball to create a filesystem image
  inspect     Display detailed information on one or more images
  load        Load an image from a tar archive or STDIN
  ls          List images
  prune       Remove unused images
  pull        Download an image from a registry
  push        Upload an image to a registry
  rm          Remove one or more images
  save        Save one or more images to a tar archive (streamed to STDOUT by default)
  tag         Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE

Run 'docker image COMMAND --help' for more information on a command.
</code>
+++

===== See Also =====
  * [[docker:ko]]
  * [[docker:builder]]
  * [[docker:buildx]]
  * [[docker:manifest]]
  * [[docker:images]]

===== History =====
  * codex:: 2026-07-06 Added docker image subpage with registry, archive, and cleanup command details.