目录

结论先说

1. 本地不存在对应镜像 → 自动拉取下载

2. 本地已经有同名同标签镜像 → 不会重复下载

3. 特殊情况：yml 里用 build 构建镜像（不是拉取）

4. 控制是否下载的常用命令

补充细节

---

结论先说

会自动下载，分两种场景：

1. 本地不存在对应镜像 → 自动拉取下载

执行 docker compose up / docker compose pull 时，docker-compose-plugin 会读取 docker-compose.yml 里 image: 字段的镜像名称 + 标签：

services:
  nginx:
    image: nginx:1.25

• 本地没有 nginx:1.25 → 插件调用 Docker Engine 去镜像仓库（默认 Docker Hub）拉取镜像完整文件，存到本地 Docker 镜像存储目录；
• 拉取过程会输出下载进度条。

2. 本地已经有同名同标签镜像 → 不会重复下载

插件会先校验本地镜像库，镜像完全存在则跳过下载，直接创建容器。

3. 特殊情况：yml 里用 build 构建镜像（不是拉取）

services:
  app:
    build: ./dockerfile
    image: myapp:v1

这种不会去外网下载，而是本地根据 Dockerfile 编译生成镜像； 如果 build 内部 FROM 的基础镜像本地没有，依旧会自动下载基础镜像。

4. 控制是否下载的常用命令

1. 只拉取镜像，不启动容器

docker compose pull

强制检查并下载缺失镜像。

1. 启动时自动按需拉取（最常用）

docker compose up -d

缺镜像自动下，已有则直接启动。

1. 禁止拉取，本地无镜像直接报错

docker compose up --pull never

本地不存在对应镜像就启动失败，不会联网下载。

1. 每次启动都强制重新拉取最新镜像

docker compose up --pull always

无论本地有没有，都重新下载镜像覆盖。

补充细节

1. 下载的镜像和 docker pull xxx 存在同一个本地镜像存储区，用 docker images 可以查到；
2. 镜像下载完成后永久保存在本地，除非手动执行 docker rmi 镜像名 删除；
3. 私有仓库镜像（harbor 等）只要 yml 里写全地址，插件同样会自动登录拉取。