「pull access denied, repository does not exist or may require docker login」エラーの解決方法

エラーの状況

コマンドライン、Dockerfileのビルド、または docker-compose up から docker pull を実行すると、Dockerが以下のエラーを返します：

$ docker pull mycompany/myapp:latest
Error response from daemon: pull access denied for mycompany/myapp,
repository does not exist or may require 'docker login':
denied: requested access to the resource is denied

完全なエラーメッセージはこちらです：

pull access denied, repository does not exist or may require 'docker login'

このエラーには3つの原因が考えられます：認証されていない、イメージ名にタイポがある、またはリポジトリが存在しない。それぞれ対処法が異なります。

原因

レジストリにログインしていない — プライベートリポジトリは、存在確認の前に認証が必要です
イメージ名またはタグのタイポ — nginx:lastest と nginx:latest を間違えるのはよくあるミスです
レジストリの指定が違う — イメージがDocker Hubではなく ghcr.io やセルフホストのレジストリにある場合
イメージがプッシュされていない、または削除された — リポジトリが実際に存在しない場合
認証情報の期限切れまたは失効 — Docker Hubの個人アクセストークンはデフォルトで1年後に期限切れになります（手動でローテーションした場合は即時失効）

素早い診断

現在のログイン状態を確認する

cat ~/.docker/config.json

auths キーを確認してください。空のオブジェクト、またはレジストリURLが見つからない場合はログインしていません。これが原因です。

イメージ名を確認する

# Docker Hubでパブリックイメージを検索
docker search postgres

# APIで利用可能なタグを確認
curl -s "https://hub.docker.com/v2/repositories/library/node/tags/?page_size=10" | python3 -m json.tool | grep '"name"'

docker-compose.yml やDockerfileで正確なイメージ参照を確認してください。名前空間の欠落（myapp vs myorg/myapp）や1文字のタグのタイポは意外と見逃しやすいです。

解決策1 — Docker Hubにログインする

ほとんどの場合、これだけで解決します：

docker login

Docker Hubのユーザーネームとパーソナルアクセストークンを入力します。DockerはCLI認証でのパスワード直接入力を廃止しました。hub.docker.com → アカウント設定 → セキュリティ → 新しいアクセストークンからトークンを生成してください。

以下のように表示されれば成功です：

Login Succeeded

その後、再度pullを実行します：

docker pull mycompany/myapp:latest

解決策2 — Docker Hub以外のレジストリにログインする

レジストリの指定ミスは見落としやすい原因です。イメージ名は正しく見えても、Docker Hub以外の場所にある場合があります。

GitHub Container Registry (ghcr.io)

docker login ghcr.io -u YOUR_GITHUB_USERNAME -p YOUR_GITHUB_TOKEN
docker pull ghcr.io/owner/image:tag

GitHubトークンには read:packages スコープが必要です。これがないと、有効な認証情報でも同じアクセス拒否エラーが発生します。

AWS ECR

aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789.dkr.ecr.us-east-1.amazonaws.com

docker pull 123456789.dkr.ecr.us-east-1.amazonaws.com/myimage:latest

セルフホストレジストリ

docker login registry.mycompany.com
docker pull registry.mycompany.com/myapp:latest

解決策3 — イメージ名を修正する

ログイン後もエラーが続く場合、イメージ名が間違っている可能性があります。よくあるミスは以下の通りです：

名前空間の欠落：myorg/myapp のところを myapp と指定している
レジストリプレフィックスの欠落：registry.mycompany.com/myimage のところを myimage と指定している
タグのタイポ：:lastest、:mian、または実際に公開されているタグが :3.1.0 なのに :3.1 と指定している

# ローカルのイメージと比較する
docker images

# 確認済みの正確な名前でpullする
docker pull nginx:1.25-alpine

恒久的な解決策 — 認証情報の永続化

毎回 docker login を実行するのは面倒です。クレデンシャルヘルパーを使えば、ログイン情報を安全に保存してDockerが自動的に認証を処理します。

Linux

# passベースのクレデンシャルヘルパーをインストール
VERSION=0.8.0
wget https://github.com/docker/docker-credential-helpers/releases/download/v${VERSION}/docker-credential-pass-v${VERSION}.linux-amd64
chmod +x docker-credential-pass-v${VERSION}.linux-amd64
sudo mv docker-credential-pass-v${VERSION}.linux-amd64 /usr/local/bin/docker-credential-pass

# Dockerに使用するよう設定
mkdir -p ~/.docker
echo '{"credsStore": "pass"}' > ~/.docker/config.json

macOS / Windows

Docker Desktopが自動的に処理します。認証情報はシステムキーチェーンに保存されます。一度 docker login すれば、再起動後も持続します。

CI/CDパイプラインの場合

GitHub ActionsやGitLab CIでこのエラーが出た場合、ランナーにはDockerの認証情報がプリロードされていません。明示的なログインステップが必要です。

# GitHub Actions
- name: Docker Hubにログイン
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKERHUB_USERNAME }}
    password: ${{ secrets.DOCKERHUB_TOKEN }}

# GitLab CI
before_script:
  - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY

認証情報はCIプラットフォームのシークレットマネージャーで管理してください。設定ファイルにハードコードすると深刻なセキュリティインシデントにつながります。

修正の確認

ログインまたはイメージ名の修正後：

docker pull mycompany/myapp:latest

pullが成功した場合、以下のように表示されます：

latest: Pulling from mycompany/myapp
a8b37f1f5f40: Pull complete
Digest: sha256:abc123...
Status: Downloaded newer image for mycompany/myapp:latest

ローカルに保存されたことを確認します：

docker images | grep myapp

ヒント

本番環境では明示的なバージョンタグを指定してください — myapp:1.4.2 は myapp:latest よりはるかに安全です。latest は次のプッシュ後に別のイメージを指す可能性があります
アクセストークンは定期的にローテーションしてください。pull専用トークンには読み取り権限のみ必要です。デプロイ用サービスアカウントに書き込み権限を付与する必要はありません
セルフホストレジストリのサービスアカウントをプロビジョニングする際は、強力なランダムパスワードを使用してください。ToolCraftのパスワードジェネレーターはクライアントサイドで動作し、サーバーには何も送信しません
チームの docker-compose ワークフローでは、セットアップスクリプトやMakefileに docker login を追加してください。新しいチームメンバーが初日にこのエラーに遭遇せずに済みます