简介面向需要快速掌握Python Web开发环境搭建的初学者这份PDF简明梳理了Django模块的安装方法重点对比了pip安装与源码包手动安装两种途径并针对pip访问报错给出了切换国内镜像源的思路同时包含创建Django项目时缺失sqlparse、pytz等依赖模块的下载地址与安装示例。全文共1个PDF文件压缩包体积仅43KB便于移动设备随时查阅。已有804人学习下载适合刚接触Django、希望在PyCharm或命令行中完成环境配置与项目创建的新手。通过这份资料读者可以避开常见安装坑点按步骤完成Django部署并理解依赖模块的补充安装逻辑为后续开发Web应用打下基础。内容预览还展示了创建项目、导入已有项目的完整流程能帮助初学者从零建立可运行的Django开发环境。1. Django 模块装不上多数人的第一道坎其实是安装方式接触 Python Web 开发的人第一件事就是装 Django而这一关的信息差比想象中大。网上大量教程默认你敲一行pip install django就能搞定但真正动手时超时、连接被重置、SSL 报错轮番上演。很多人以为是自己环境坏了折腾半天才发现是默认 PyPI 源在国内网络环境下响应不稳定。这篇文章直接把两种安装路线讲透pip 在线安装的换源方案和 tar.gz 离线手动安装流程顺带把创建项目时最容易缺失的 sqlparse、pytz 依赖提前补上。此外还会拆解 PyCharm 社区版与专业版在 Django 项目导入上的差异读完可以不看其他教程直接照着操作。2. 装之前先对齐版本Python 版本与 Django 版本的匹配规则2.1 为什么说版本号必须对应原笔记里反复强调“网上搜一下对应的版本号版本号相对应”这句话看着简单实际是大坑。Django 对 Python 版本有明确支持范围比如 Django 2.2 支持 Python 3.5 以上的版本Django 3.2 LTS 支持 Python 3.6 以上的版本Django 4.x 要求 Python 3.8 以上Django 5.x 则需要 Python 3.10 以上。如果你用 Python 3.7 硬装 Django 4.2安装过程不会直接拦截但运行项目时会冒出django.core.exceptions.ImproperlyConfigured这类错误定位起来反而更绕。我一般会在安装前先确认当前 Python 版本python --version输出类似Python 3.11.5这样的信息。然后去 Django 官方 Release 页面查一下这个 Python 版本支持的最新 Django 主版本。有个简单的对应规则Python 3.11 可装 Django 4.2.x 或 5.0.xPython 3.8 则建议锁定 Django 3.2.x 或 4.0.x。这样选型清楚了后面碰到问题也好判断是版本兼容还是代码问题。2.2 虚拟环境是降低版本冲突的第一道护栏直接往 Python 全局 site-packages 里装 Django一台机器上如果同时有多个项目依赖不同 Django 版本就会互相覆盖。这就是不建虚拟环境直接装的后果A 项目能用B 项目启动直接崩。新建项目时我基本会先建虚拟环境python -m venv myenvWindows 下激活命令myenv\Scripts\activatemacOS 或 Linux 下激活命令source myenv/bin/activate激活后命令行提示符会显示(myenv)前缀。此后所有 pip 安装和 django-admin 操作都在这个隔离环境内不会再污染全局 Python。很多初学的人跳过这一步等到安装 sqlparse 或 pytz 时发现系统里已经有一堆同名包版本互相干扰项目启动时 import 报错浪费大量时间。3. pip 安装 Django 的完整流程换源、建项目、验证三步走3.1 直接 pip install 为何会失败pip install django默认访问 pypi.org国内网络环境下经常出现ReadTimeoutError或Connection reset by peer。这不是 pip 工具坏了而是源服务器连接不稳定。解决办法是换国内镜像源阿里云、豆瓣、清华的 PyPI 镜像都可选。换源后下载速度能明显提升默认源超时的问题基本消失。我实际使用频率最高的做法是临时指定源pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple也可以写成阿里云源pip install django -i https://mirrors.aliyun.com/pypi/simple/临时指定源的优点是只影响这一次安装不会改动全局配置。如果你希望长期生效可以修改 pip 配置文件pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这个命令会把清华源写入 pip 全局配置之后所有 pip 安装默认走国内源超时率明显变低。注意镜像源会有同步延迟新版本发布后可能要等几个小时才能从镜像源拉到如果提示找不到某个版本过段时间再试或换一个源。3.2 验证安装结果与版本信息安装完成后验证是否真的装上python -m django --version能打印出版本号比如4.2.5说明 Django 核心已经安装成功。这里多说一句不要用pip show django代替导入验证pip show看到的只是包元数据而python -m django --version是真正加载 Django 的代码后才能跑出来的结果。两者差异在于后者能提前暴露导入阶段的问题比如缺少某些 C 扩展或路径配置出错。有些情况下python -m django也能运行但直接执行django-admin却提示命令找不到。原因通常是 Python 的 Scripts 目录没加入系统 PATH。Windows 下 Scripts 目录一般在C:\Users\用户名\AppData\Local\Programs\Python\Python311\ScriptsmacOS 和 Linux 则在虚拟环境的bin目录。遇到这种情况把对应目录加到 PATH或者干脆全程用python -m django代替django-admin效果一样。3.3 用 pip 安装时顺手解决依赖缺失创建 Django 项目时如果提示缺少模块常见的是sqlparse和pytz。sqlparse 用于 SQL 语句格式化Django 的 migrations 模块会用到pytz 处理时区转换settings.py 里设置了非 UTC 时区时就会加载。这两个包在 Django 安装时不一定自动带上缺少时项目创建会中断。遇到这种报错先用 pip 补装pip install sqlparse pytz -i https://pypi.tuna.tsinghua.edu.cn/simple装完后再执行django-admin startproject即可。这里有个小提示如果发现 pip 安装这两个包成功但 Django 依然报缺模块检查一下是不是安装进了全局环境而 Django 运行在虚拟环境中。用pip list确认当前环境的包列表保持所有依赖都装在同一环境中是基本操作。4. 离线手动安装 tar.gz 包官网下载、解压、setup.py 三步安装法4.1 为什么还要掌握离线安装有的开发环境无法直连外部网络或者公司内网只允许访问白名单域名pip 即使换了国内源也连不上。此时手动下载 tar.gz 包成了唯一出路。Django 官网上每个版本都提供源码包文件名类似Django-5.0.2.tar.gz。这份笔记里写的就是这个路线也被证明是最稳的兜底方案。下载时注意选择和你 Python 版本匹配的 Django 版本。下载后的 tar.gz 包放入一个固定目录我习惯放在 Python 安装目录外的单独文件夹比如D:\downloads\django避免污染 Python 安装目录。4.2 解压并执行安装命令Windows 下可以直接用鼠标右键解压也可以用命令tar -zxvf Django-5.0.2.tar.gzmacOS 和 Linux 下同样用这条命令。解压后进入解压出来的目录cd Django-5.0.2然后执行安装python setup.py install这里说明一下python setup.py install是传统的安装方式直接复制文件到 site-packages。比较新的写法是pip install .后者会先构建 wheel 再安装还能自动处理依赖声明。但在没有外网的环境里如果依赖包也缺失pip install .反而会因为拉取不到依赖而失败。此时python setup.py install反而更直接它只安装 Django 本身的文件缺什么依赖你后续单独手动补。安装过程看到类似Finished processing dependencies for Django或Installed ...的提示基本就结束了。4.3 手动安装后也需验证导入打开一个新的命令行窗口进入 Python 交互模式import django print(django.get_version())输出类似5.0.2的版本号即安装成功。这一步很关键因为setup.py install不会输出太多成功信息很多人装完不确定是否有问题。用导入命令验证是最直接的方法。这里多提一句验证时一定要在你要用的那个 Python 环境里跑。如果电脑上装了多个 Python 版本命令行输入python时进入的可能是另一个版本安装到了 Python 3.11 却用 Python 3.8 来验证自然会报 ModuleNotFoundError。如果你的 Django 安装在虚拟环境中先激活虚拟环境再执行上述导入验证。这一点是新手最容易踩坑的地方。4.4 手动安装依赖包的补充流程在离线环境下sqlparse 和 pytz 同样只能手动安装。去 PyPI 页面下载对应 tar.gz 包PyPI 每个项目的 files 页面会列出所有历史版本按需下载即可。命令流程和 Django 安装一致tar -zxvf sqlparse-0.4.4.tar.gz cd sqlparse-0.4.4 python setup.py installpytz 也是同样操作。这些包依赖很少手动安装不会遇到复杂的传递依赖问题大多数情况下一条命令走完。装好后再次验证导入import sqlparse print(sqlparse.__version__)输出版本号即成功。5. 安装坑排查与风险排查从报错现象到根因定位5.1 现象pip 安装时持续超时或连接重置这类问题在新手群和论坛里出现频率很高表现为进度条长时间不动然后直接抛出ReadTimeoutError或Connection reset by peer。原因是默认 PyPI 源服务器在部分网络环境下响应不稳定ping 能通但实际数据传输被中断。解决方式有两种优先推荐临时换源。执行pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple下载速度会快很多。若临时换源仍然超时尝试其他镜像源豆瓣源或阿里云源都可以。另一种方式是配置全局源使用pip config set global.index-url写入持久化配置避免每次安装都要手动加参数。5.2 现象django-admin 提示命令不存在Windows 系统上装完 Django 后尝试执行django-admin startproject却提示django-admin 不是内部或外部命令。原因在于 Django 安装后生成的可执行文件所在目录未加入系统 PATH。Python 的 Scripts 目录在 Windows 下通常为C:\Users\用户名\AppData\Local\Programs\Python\Python311\Scripts如果安装时没有勾选 Add to PATH该目录就不会被系统自动识别。解决方式有两种。一是手动把 Scripts 目录加入系统环境变量 PATH。二是使用python -m django startproject代替django-admin这个命令同样能创建项目不依赖 PATH 配置。我会优先推荐第二种方式因为在前者解决之前可以立刻开工。5.3 现象创建项目时报 MissingDependency 或 ModuleNotFoundError执行django-admin startproject mysite时直接报ModuleNotFoundError: No module named sqlparse。原因很简单Django 部分功能依赖 sqlparse 和 pytz这些第三方库不会随 Python 自动安装某些 Django 版本也不会自动拉取它们。解决方式是在同一环境中补装缺漏依赖。在线环境执行pip install sqlparse pytz离线环境按前面手动流程补装。装完后重新执行创建项目命令即可。这块要提醒一个细节不要只装提示缺失的那一个包sqlparse 和 pytz 最好一起检查因为它们经常连锁缺失。5.4 现象PyCharm 里打开项目后无法识别 Django 配置在 PyCharm 中打开创建好的项目右上角没有 Django 的运行配置代码里的from django.db import models也被标红。原因在于 PyCharm 使用的解释器和你命令行安装时使用的 Python 环境不一致。比如命令行用的是虚拟环境PyCharm 却选了系统全局解释器Django 在虚拟环境里PyCharm 找不到。解决方式是打开 PyCharm 的 Settings 页面找到 Python Interpreter 设置项选择你安装 Django 时对应的解释器。如果使用的是虚拟环境在该设置页面点击齿轮图标添加已有虚拟环境路径即可。解释器切换成功后PyCharm 会自动扫描并识别 Django 库红色报错会消失。如果是 PyCharm 专业版还需要在 Settings 里找到 Django 设置项指定项目根目录和 settings.py 文件Django 控制台的运行配置才会显示出来。5.5 现象手动安装 Django 后其他项目无法启动从官网下载 tar.gz 包手动安装的 Django 用了一段时间新项目突然在启动时报模板找不到或配置加载异常。原因通常是手动安装将 Django 写入了某个固定目录后期该目录被移动、重命名或手动清理过Python 在 sys.path 中无法再找到正确路径。解决方式很简单重新执行一次python setup.py install即可让文件回到正确位置。如果是全局环境出问题重装后还需确认没有其他残留的旧版本目录干扰。更稳的方案是在某个稳定目录保留 Django 源码包方便随时重装。6. 把安装验证固化到每一次环境迁移中从建项目到跑通页面的最小闭环环境装好只是起点真正该做的是把一套可复现的验证流程固化下来每次换机器、换环境、换版本都能快速确认 Django 可用。我提供的做法是建立一个小项目清单用它走完创建到访问页面的完整闭环任何一个环节出错都能定位到具体模块。第一步创建测试项目python -m django startproject verify_site注意这里我用python -m django而不是django-admin是为了顺带验证 PATH 是否配置正确。如果这条命令创建目录成功说明 Django 命令行工具能正常调用。若提示无法找到模块则说明当前 Python 环境与 Django 安装环境不一致需要立即检查解释器路径。第二步启动开发服务器python verify_site/manage.py runserver 127.0.0.1:8000看到Starting development server日志后浏览器访问http://127.0.0.1:8000/页面显示 Django 默认的火箭页面说明 Django 核心功能、URL 路由和应用实例都正常。这里要关注的一点是端口号是否被占用如果 8000 端口被其他进程占用可以换8080或8001重新启动。第三步验证数据库配置python verify_site/manage.py migrate这条命令会初始化 Django 默认的 SQLite 数据库。如果执行过程中报 sqlparse 缺失或数据库相关错误正好可以同步补齐依赖。migrate 成功后项目目录下会生成一个db.sqlite3文件这能证明 Django 能正常连接数据库引擎。第四步额外验证时区相关配置。在 settings.py 中将TIME_ZONE设置成UTC以外的值如Asia/Shanghai保存后再执行python verify_site/manage.py check如果 pytz 没有正确安装这一步会报时区模块读取异常。通过这个动作可以直接确认 pytz 是否真的可用而不只是在 pip list 里能看到名字。这套流程走下来大约需要五分钟但可以避免很多后续开发中的隐性报错。自从有一次在本地环境安装阶段省去了验证结果项目开发到一半才发现某个依赖没生效导致部署时反复调试无头绪从那以后我每次装完 Django 都会强制走一遍这套验证流程创建项目、启动服务器、跑迁移、改时区配置四个动作都不少。希望这套方法也能帮你把安装阶段的问题全部拦截下来后面写业务逻辑时少踩环境坑。本文还有配套的精品资源点击获取