PyCharm Professional 版本是硬性前提，Community 版不支持 Docker 解释器配置；需确保本地 Docker Daemon 运行且可访问，镜像应指定小版本如 python:3.11.9-slim，挂载路径须正确配置并注意权限，容器内安装的包默认不持久。
PyCharm Professional 版本是硬性前提
免费的 Community 版不支持 Docker 解释器配置，会直接灰掉相关选项。如果你点开 File → Settings → Project → Python Interpreter 后看不到 Add... 按钮里的 Docker 或 Docker Compose 项，先确认是否在用 Professional 版——这不是设置问题，是功能缺失。
本地 Docker Daemon 必须运行且可被 PyCharm 访问
PyCharm 不会帮你启动 Docker，它只通过 Unix socket（Linux/macOS）或 named pipe（Windows）连接本地 daemon。常见失败现象：Connection refused 或 Cannot connect to the Docker daemon。
- macOS：确保 Docker Desktop 已启动，且
docker version命令能正常返回 - Linux：检查用户是否在
docker用户组里（否则需加sudo，但 PyCharm 默认不走 sudo） - Windows：仅支持 Docker Desktop（WSL2 backend），不支持旧版 Docker Toolbox
PyCharm 默认使用 unix:///var/run/docker.sock（Linux/macOS）或 npipe:////./pipe/docker_engine（Windows），路径不对或权限不足都会导致配置卡在“Testing interpreter”阶段超时。
选择镜像时优先用官方 Python 标签而非 latest
在添加 Docker 解释器界面中，Image name 输入框填的是镜像名+标签，例如 python:3.11-slim。别填 python:latest——它可能指向 3.12，而你的项目依赖只兼容 3.11，导致后续 pip install 报错。
立即学习“Python免费学习笔记（深入）”；
- 推荐写死小版本号，如
python:3.11.9-slim，避免 CI/CD 环境和本地行为不一致 - 如果项目需要特定系统工具（如
gcc、libpq），选python:3.11（带 build-essential）而非-slim镜像 - 自建镜像需提前
docker pull your-registry/python-project:dev，PyCharm 不会自动拉取未缓存的私有镜像
配置成功后，PyCharm 会在容器内执行 python -c "import sys; print(sys.executable)" 来验证解释器路径，这个过程会创建一个临时容器并立即退出。如果你的 Dockerfile 里有 CMD 或 ENTRYPOINT 导致容器无法快速退出，PyCharm 会卡住或报错。
挂载项目目录时注意路径映射与权限
PyCharm 默认把当前项目根目录挂载进容器的 /project（Linux/macOS）或 C:/project（Windows）。但实际路径取决于你本地项目位置和 Docker 的文件共享设置：
- macOS/Windows：Docker Desktop 的
Resources → File Sharing列表必须包含你的项目所在父目录，否则挂载失败，表现为解释器里看不到任何.py文件 - Linux：确保挂载路径对容器内用户可读（比如宿主机用 root 创建的文件，在容器里可能是
uid=0，但 PyCharm 启动的容器默认以非 root 用户运行） - 若用 Docker Compose 方式配置，PyCharm 会读取
docker-compose.yml中的volumes，但只认第一个 service 且忽略environment和depends_on
最常被忽略的一点：容器内安装的包（如通过 PyCharm 界面点 + 装的 requests）只存在于该临时容器中，下次重启解释器会丢失——除非你把 /root/.local 或 /usr/local/lib/python3.x/site-packages 也挂载为卷，或者改用 Docker Compose + build 流程固化依赖。
