如何在PyCharm Docker环境中使用uv run运行Django项目？

一、核心配置步骤 #

PyCharm目前没有内置uv专属的运行模板，我们可以通过自定义Python运行配置实现需求：

1. 确认容器内uv的绝对路径 #

进入你的Docker容器，执行以下命令获取uv路径：

which uv

记下输出结果（比如/usr/local/bin/uv），后续配置会用到。

2. 创建自定义运行配置 #

1. 点击PyCharm右上角运行按钮旁的下拉框，选择「Edit Configurations...」
2. 点击左上角「+」，选择「Python」模板
3. 配置关键参数：
   • Name：自定义名称，比如「Django Dev (uv run)」
   • Script path：填入刚才获取的uv绝对路径（如/usr/local/bin/uv）
   • Parameters：输入run python manage.py runserver 0.0.0.0:8000（uv run的语法是uv run <命令>，这里直接调用Python执行manage.py）
   • Working directory：设置为容器内的Django项目根目录（比如/app，要和你的Docker路径映射一致）
   • Python interpreter：选择已配置好的Docker容器解释器（未配置的话看下方补充步骤）
4. 点击「Apply」保存配置，之后就能用这个配置启动Django开发服务

补充：配置Docker解释器（未配置的情况） #

1. 打开「File > Settings > Project: [你的项目名] > Python Interpreter」
2. 点击齿轮图标，选择「Add...」
3. 选择「Docker」选项，关联你的Docker服务，指定对应的容器或镜像，确保本地项目目录和容器内目录正确映射
4. 确认后，回到运行配置选择这个解释器即可

二、最佳实践 #

• 优化Docker构建速度：在Dockerfile中提前安装uv并缓存依赖层，示例：

  FROM python:3.12-slim
  WORKDIR /app
  
  # 安装uv
  RUN curl -LsSf https://astral.sh/uv/install.sh | sh
  
  # 先复制依赖文件，利用Docker缓存
  COPY pyproject.toml uv.lock ./
  RUN uv sync --dev  # 开发环境加--dev，生产环境去掉
  
  # 最后复制项目代码
  COPY . .
  

• 日常依赖管理：用uv add <包名>安装新依赖，uv sync更新依赖，替代pip相关命令，速度更快且自动维护锁文件
• 共享配置：将运行配置保存为项目文件（勾选配置界面的「Store as project file」），方便团队成员直接使用
• 调试注意事项：确保本地与容器的路径映射完全一致，避免断点无法命中或文件找不到的问题

三、替代方案 #

如果自定义Python配置觉得繁琐，可以试试这两种方式：

• Shell脚本启动：在项目根目录创建start-dev.sh：

  #!/bin/bash
  uv run python manage.py runserver 0.0.0.0:8000
  

  然后在PyCharm中创建「Shell Script」运行配置，指向该脚本，工作目录设为项目根，解释器选Docker容器的Shell
• Docker Compose启动：在docker-compose.yml的服务中指定启动命令：

  services:
    web:
      build: .
      command: uv run python manage.py runserver 0.0.0.0:8000
      volumes:
        - ./:/app
      ports:
        - "8000:8000"
  

  之后在PyCharm中直接关联Docker Compose服务作为运行目标即可

内容的提问来源于stack exchange，提问作者Nori