From 8665fdfb049ea8d7c84bc17e2e18cfc8d1f1f085 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Thu, 6 Aug 2026 23:46:45 +0500
Subject: [PATCH] docs: warn that sudo docker login often writes root's
 config.json

$HOME under sudo is usually /root, so credentials miss the invoking
user's ~/.docker and later non-sudo commands look logged out.

Fixes #5384

Signed-off-by: Dean Chen <862469039@qq.com>
---
 docs/reference/commandline/login.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/reference/commandline/login.md b/docs/reference/commandline/login.md
index a4e443bcaabd..3bff87d47e1e 100644
--- a/docs/reference/commandline/login.md
+++ b/docs/reference/commandline/login.md
@@ -35,6 +35,13 @@ credential store, Docker stores credentials in the `config.json` file in a
 base64-encoded format. This method is less secure than configuring and using a
 credential store.
 
+On Linux, prefer running `docker login` as your normal user. Prefixing the
+command with `sudo` often changes `$HOME` to `/root`, so credentials land in
+`/root/.docker/config.json` instead of your user's file — later non-sudo
+`docker` commands then look unauthenticated. If you must use root, pass
+`sudo -E` or set `DOCKER_CONFIG` to the directory that should hold
+`config.json`.
+
 `docker login` also supports [credential helpers](#credential-helpers) to help
 you handle credentials for specific registries.