设置 Django 开发环境

既然您已经了解了 Django 的作用，我们将向您展示如何在 Windows、Linux (Ubuntu) 和 macOS 上设置和测试 Django 开发环境——无论您使用哪种常用操作系统，本文都将为您提供开始开发 Django 应用程序所需的一切。

预备知识	具备使用终端/命令行以及如何在开发计算机的操作系统上安装软件包的基本知识。
目标	在您的计算机上运行 Django (4.*) 的开发环境。

Django 开发环境概述

Django 使您可以在自己的计算机上轻松设置，以便开始开发 Web 应用程序。本节解释了开发环境的功能，并概述了一些设置和配置选项。本文的其余部分解释了在 Ubuntu、macOS 和 Windows 上安装 Django 开发环境的推荐方法，以及如何测试它。

什么是 Django 开发环境？

开发环境是 Django 在您本地计算机上的安装，您可以使用它来开发和测试 Django 应用程序，然后再将其部署到生产环境。

Django 本身提供的主要工具是一组用于创建和使用 Django 项目的 Python 脚本，以及一个简单的开发 Web 服务器，您可以使用它在计算机的 Web 浏览器上测试本地（即在您的计算机上，而不是在外部 Web 服务器上）Django Web 应用程序。

还有其他外围工具，通常是开发环境的一部分，我们不会在这里介绍。这些包括用于编辑代码的文本编辑器或 IDE，用于自动格式化的代码检查器等。我们假设您已经安装了文本编辑器。

Django 有哪些设置选项？

Django 在安装和配置方式上非常灵活。Django 可以

安装在不同的操作系统上。
从源代码、Python 包索引 (PyPi) 安装，在许多情况下还可以从主机计算机的包管理器应用程序安装。
配置为使用多个数据库之一，这些数据库可能也需要单独安装和配置。
在主系统 Python 环境中运行或在单独的 Python 虚拟环境中运行。

这些选项中的每一个都需要略有不同的配置和设置。以下小节解释了您的一些选择。对于本文的其余部分，我们将向您展示如何在少数几个操作系统上设置 Django，并且该设置将在本模块的其余部分中假定。

注意：其他可能的安装选项在官方 Django 文档中有所介绍。我们链接到下面的相应文档。

支持哪些操作系统？

Django Web 应用程序几乎可以在任何可以运行 Python 3 编程语言的机器上运行：Windows、macOS、Linux/Unix、Solaris 等等。几乎任何计算机都应该具有在开发过程中运行 Django 所需的性能。

在本文中，我们将提供 Windows、macOS 和 Linux/Unix 的说明。

应该使用哪个版本的 Python？

您可以使用目标 Django 版本支持的任何 Python 版本。对于 Django 5.0，允许的版本是 Python 3.10 到 3.12（请参阅常见问题解答：安装）。

Django 项目建议（并“官方支持”）使用受支持的 Python 版本的最新可用版本。

我们可以在哪里下载 Django？

有三个地方可以下载 Django

Python 包仓库 (PyPi)，使用 pip 工具。这是获取 Django 最新稳定版本的最佳方式。
使用计算机包管理器中的版本。与操作系统捆绑在一起的 Django 发行版提供了一种熟悉的安装机制。但是请注意，打包版本可能相当旧，并且只能安装到系统 Python 环境中（这可能不是您想要的）。
从源代码安装。您可以从源代码获取并安装 Django 的最新前沿版本。不建议初学者使用此方法，但在您准备开始为 Django 本身贡献代码时是必需的。

本文演示了如何从 PyPi 安装 Django，以获取最新的稳定版本。

哪个数据库？

Django 官方支持 PostgreSQL、MariaDB、MySQL、Oracle 和 SQLite 数据库，并且有社区库为其他流行的 SQL 和 NoSQL 数据库提供不同级别的支持。我们建议您在生产和开发中使用相同的数据库（尽管 Django 使用其对象关系映射器 (ORM) 抽象了许多数据库差异，但仍然存在最好避免的潜在问题）。

对于本文（以及本模块的大部分内容），我们将使用 SQLite 数据库，它将数据存储在文件中。SQLite 旨在用作轻量级数据库，不能支持高并发性。然而，它对于主要只读的应用程序来说是一个绝佳的选择。

注意：当您使用标准工具 (django-admin) 启动您的网站项目时，Django 默认配置为使用 SQLite。当您刚开始时，这是一个不错的选择，因为它不需要额外的配置或设置。

系统范围安装还是在 Python 虚拟环境中安装？

当您安装 Python3 时，您会获得一个由所有 Python3 代码共享的全局环境。虽然您可以在环境中安装任何您喜欢的 Python 包，但一次只能安装每个包的一个特定版本。

注意：安装到全局环境中的 Python 应用程序可能会相互冲突（即，如果它们依赖于相同包的不同版本）。

如果您将 Django 安装到默认/全局环境中，那么您将只能在计算机上针对一个版本的 Django。如果您想创建新网站（使用最新版本的 Django），同时仍维护依赖于旧版本的网站，这可能会成为一个问题。

因此，经验丰富的 Python/Django 开发人员通常在独立的 Python 虚拟环境中运行 Python 应用程序。这允许在单个计算机上存在多个不同的 Django 环境。Django 开发团队本身建议您使用 Python 虚拟环境！

本模块假设您已将 Django 安装到虚拟环境中，我们将在下面向您展示如何操作。

安装 Python 3

为了使用 Django，您的操作系统上必须有 Python 3。您还需要 Python 包索引工具 — pip3 — 它用于管理（安装、更新和删除）Django 和您的其他 Python 应用程序使用的 Python 包/库。

本节简要说明了如何在 Ubuntu Linux 20.04、macOS 和 Windows 10 上检查存在哪些 Python 版本，并在需要时安装新版本。

注意：根据您的平台，您还可以从操作系统的包管理器或通过其他机制安装 Python/pip。对于大多数平台，您可以从 https://pythonlang.cn/downloads/ 下载所需的安装文件，并使用相应的平台特定方法进行安装。

Ubuntu 22.04

Ubuntu Linux 22.04 LTS 默认包含 Python 3.10.12。您可以通过在 bash 终端中运行以下命令来确认这一点

bash

python3 -V
# Output: Python 3.10.12

但是，安装 Python 3 包（包括 Django）所需的 Python 包索引工具 (pip3) 不是默认可用的。您可以使用以下命令在 bash 终端中安装 pip3

bash

sudo apt install python3-pip

注意：Python 3.10 是 Django 5.0 支持的最旧版本。您不需要为此教程使用最新版本的 Python，但如果您想使用，互联网上有很多说明。

macOS

macOS 默认不包含 Python 3（旧版本包含 Python 2）。您可以通过在终端中运行以下命令来确认这一点

bash

python3 -V

这将显示 Python 版本号（表示 Python 3 已安装），或者显示 python3: command not found（表示未找到 Python 3）。

您可以从 python.org 轻松安装 Python 3（以及 pip3 工具）

下载所需的安装程序
1. 访问 https://pythonlang.cn/downloads/macos/
2. 下载与 Django 5.0 兼容的受支持版本的最新稳定版本。（撰写本文时为 Python 3.11.8）。
使用 Finder 找到该文件，然后双击包文件。按照安装提示进行操作。

您现在可以通过再次运行 python3 -V 并检查 Python 版本号来确认安装成功。

您可以通过列出可用包来类似地检查是否安装了 pip3

bash

pip3 list

Windows 10 或 11

Windows 默认不包含 Python，但您可以从 python.org 轻松安装它（以及 pip3 工具）

下载所需的安装程序
1. 访问 https://pythonlang.cn/downloads/windows/
2. 下载与 Django 5.0 兼容的受支持版本的最新稳定版本。（撰写本文时为 Python 3.11.8）。
双击下载的文件并按照安装提示安装 Python
务必勾选“将 Python 添加到 PATH”复选框

然后，您可以通过在命令提示符中输入以下文本来验证 Python 3 是否已安装

bash

py -3 -V

Windows 安装程序默认包含 pip3（Python 包管理器）。您可以按如下所示列出已安装的包

bash

py -3 -m pip list

注意：安装程序应该设置好您需要的所有东西，以便上述命令能够正常工作。但是，如果您收到 Python 找不到的消息，您可能忘记将其添加到您的系统路径。您可以通过再次运行安装程序，选择“修改”，并在第二页上勾选“将 Python 添加到环境变量”复选框来完成此操作。

在 Python 虚拟环境中使用 Django

我们将用于创建虚拟环境的库是 virtualenvwrapper（Linux 和 macOS）和 virtualenvwrapper-win（Windows），它们都使用 virtualenv 工具。wrapper 工具为所有平台上的接口管理创建了一个一致的接口。

安装虚拟环境软件

Ubuntu 虚拟环境设置

安装 Python 和 pip 后，您可以安装 virtualenvwrapper（其中包括 virtualenv）。您可以查看官方安装指南，或按照以下说明进行操作。

使用 pip3 安装工具

bash

sudo pip3 install virtualenvwrapper

然后将以下行添加到您的 shell 启动文件末尾（这是一个名为 .bashrc 的隐藏文件，位于您的主目录中）。这些设置了虚拟环境的存放位置、您的开发项目目录的位置以及此包安装的脚本的位置

bash

export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export VIRTUALENVWRAPPER_VIRTUALENV_ARGS=' -p /usr/bin/python3 '
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh

注意：VIRTUALENVWRAPPER_PYTHON 和 VIRTUALENVWRAPPER_VIRTUALENV_ARGS 变量指向 Python 3 的正常安装位置，source /usr/local/bin/virtualenvwrapper.sh 指向 virtualenvwrapper.sh 脚本的正常位置。如果您测试时 virtualenv 不起作用，要检查的一件事是 Python 和脚本是否在预期位置（然后相应地更改启动文件）。

您可以使用命令 which virtualenvwrapper.sh 和 which python3 找到系统正确的路径。

然后通过在终端中运行以下命令重新加载启动文件

bash

source ~/.bashrc

此时，您应该看到一堆脚本正在运行，如下所示

bash

virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/premkproject
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/postmkproject
# …
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/preactivate
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/postactivate
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/get_env_details

现在您可以使用 mkvirtualenv 命令创建一个新的虚拟环境。

macOS 虚拟环境设置

在 macOS 上设置 virtualenvwrapper 与在 Ubuntu 上几乎完全相同（同样，您可以按照官方安装指南或以下说明进行操作）。

如所示，使用 pip 安装 virtualenvwrapper（并捆绑 virtualenv）。

bash

sudo pip3 install virtualenvwrapper

然后将以下行添加到您的 shell 启动文件末尾（这些行与 Ubuntu 的相同）。如果您使用的是 zsh shell，则启动文件将是您主目录中名为 .zshrc 的隐藏文件。如果您使用的是 bash shell，则它将是名为 .bash_profile 的隐藏文件。如果文件尚不存在，您可能需要创建它。

bash

export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export PROJECT_HOME=$HOME/Devel
source /usr/local/bin/virtualenvwrapper.sh

注意： VIRTUALENVWRAPPER_PYTHON 变量指向 Python 3 的正常安装位置，source /usr/local/bin/virtualenvwrapper.sh 指向 virtualenvwrapper.sh 脚本的正常位置。如果您测试时 virtualenv 不起作用，要检查的一件事是 Python 和脚本是否在预期位置（然后相应地更改启动文件）。

例如，macOS 上的一项安装测试最终需要在启动文件中包含以下行

bash

export WORKON_HOME=$HOME/.virtualenvs
export VIRTUALENVWRAPPER_PYTHON=/Library/Frameworks/Python.framework/Versions/3.7/bin/python3
export PROJECT_HOME=$HOME/Devel
source /Library/Frameworks/Python.framework/Versions/3.7/bin/virtualenvwrapper.sh

您可以使用命令 which virtualenvwrapper.sh 和 which python3 找到系统正确的路径。

然后通过在终端中进行以下调用来重新加载启动文件

bash

source ~/.bash_profile

此时，您可能会看到一堆脚本正在运行（与 Ubuntu 安装的脚本相同）。您现在应该能够使用 mkvirtualenv 命令创建一个新的虚拟环境。

注意：如果您在 Finder 中找不到要编辑的启动文件，也可以使用 nano 在终端中打开它。

假设您正在使用 bash，命令看起来像这样

bash

cd ~  # Navigate to my home directory
ls -la #List the content of the directory. You should see .bash_profile
nano .bash_profile # Open the file in the nano text editor, within the terminal
# Scroll to the end of the file, and copy in the lines above
# Use Ctrl+X to exit nano, choose Y to save the file.

Windows 虚拟环境设置

安装 virtualenvwrapper-win 比设置 virtualenvwrapper 甚至更简单，因为您无需配置工具存储虚拟环境信息的位置（有一个默认值）。您需要做的就是在命令提示符中运行以下命令

bash

py -3 -m pip install virtualenvwrapper-win

现在您可以使用 mkvirtualenv 命令创建一个新的虚拟环境

创建一个虚拟环境

一旦您安装了 virtualenvwrapper 或 virtualenvwrapper-win，那么在所有平台上使用虚拟环境都非常相似。

现在，您可以使用 mkvirtualenv 命令创建一个新的虚拟环境。当此命令运行时，您将看到环境正在设置（您看到的内容略有平台差异）。命令完成后，新的虚拟环境将处于活动状态 — 您可以通过提示符开头括号中的环境名称来看到这一点（下面我们展示了 Ubuntu 的示例，但 Windows/macOS 的最后一行也类似）。

bash

mkvirtualenv my_django_environment

您应该会看到类似于以下内容的输出

Running virtualenv with interpreter /usr/bin/python3
# …
virtualenvwrapper.user_scripts creating /home/ubuntu/.virtualenvs/t_env7/bin/get_env_details
(my_django_environment) ubuntu@ubuntu:~$

现在您已进入虚拟环境，可以安装 Django 并开始开发了。

注意：从现在开始，在本文（以及模块）中，请假定所有命令都在我们上面设置的 Python 虚拟环境中运行。

使用虚拟环境

您还需要了解一些其他有用的命令（工具文档中有更多命令，但这些是您会经常使用的）

deactivate — 退出当前的 Python 虚拟环境
workon — 列出可用的虚拟环境
workon name_of_environment — 激活指定的 Python 虚拟环境
rmvirtualenv name_of_environment — 删除指定的环境。

安装 Django

创建虚拟环境后，并调用 workon 进入该环境，您可以使用 pip3 安装 Django。

bash

# Linux/macOS
python3 -m pip install django~=4.2

# Windows
py -3 -m pip install django~=4.2

您可以通过运行以下命令来测试 Django 是否已安装（这只是测试 Python 是否能找到 Django 模块）

bash

# Linux/macOS
python3 -m django --version

# Windows
py -3 -m django --version

注意：如果上述 Windows 命令未显示存在 django 模块，请尝试

bash

py -m django --version

在 Windows 中，Python 3 脚本通过在命令前加上 py -3 来启动，尽管这可能会因您的具体安装而异。如果您遇到任何命令问题，请尝试省略 -3 修饰符。在 Linux/macOS 中，命令是 python3。

警告：本模块的其余部分使用 Linux 命令调用 Python 3 (python3)。如果您在 Windows 上工作，请将此前缀替换为：py -3

使用 Git 和 GitHub 进行源代码管理

源代码管理 (SCM) 和版本控制工具使您能够可靠地存储和恢复源代码版本，尝试更改，并在需要时在您的实验和“已知良好代码”之间共享代码。

有许多不同的 SCM 工具，包括 git、Mercurial、Perforce、SVN (Subversion)、CVS (Concurrent Versions System) 等，以及云 SCM 托管源，例如 Bitbucket、GitHub 和 GitLab。在本教程中，我们将在 GitHub 上托管我们的代码，GitHub 是最流行的基于云的源代码托管服务之一，并使用 git 工具在本地管理我们的源代码并在需要时将其发送到 GitHub。

注意：使用 SCM 工具是良好的软件开发实践！这些说明提供了 Git 和 GitHub 的基本介绍。要了解更多信息，请参阅学习 Git。

关键概念

Git（和 GitHub）使用仓库（"repos"）作为存储代码的顶层“桶”，每个仓库通常只包含一个应用程序或模块的源代码。仓库可以是公开的，在这种情况下，代码对互联网上的所有人可见；也可以是私有的，在这种情况下，代码仅限于拥有组织或用户帐户。

所有工作都在您的仓库中特定代码“分支”上完成。当您想要备份对分支的一些更改时，您可以创建一个“提交”，它存储自上次提交到当前分支以来的所有更改。

仓库是使用名为“main”的默认分支创建的。您可以使用 git 从此分支派生其他分支，这些分支最初具有原始分支的所有提交。您可以通过添加提交来单独发展分支，然后稍后在 GitHub 上使用“Pull Request”（PR）将更改从一个分支合并到另一个分支。您还可以使用 git 在本地计算机上切换分支，例如尝试不同的事物。

除了分支，还可以在任何分支上创建 tags，然后恢复该分支在该点。

在 GitHub 上创建帐户和仓库

首先，我们将在 GitHub 上创建一个帐户（这是免费的）。然后，我们将创建一个名为“django_local_library”的仓库并进行配置，用于存储本教程其余部分中我们将开发的本地图书馆网站。

步骤如下：

访问 https://github.com/ 并创建一个帐户。
登录后，点击顶部工具栏中的 + 链接，然后选择 New repository。
填写此表单中的所有字段。虽然这些不是强制性的，但强烈建议填写。
- 输入仓库名称：“django_local_library”。
- 输入新的仓库描述：“用 Django 编写的本地图书馆网站”。
- 为仓库选择“Public”（默认）。
  
  警告：这将使所有源代码可见。请记住，除非您的仓库是私有的，否则不要在其中存储凭据或其他敏感材料。
- 在 Add .gitignore 选择列表中选择 Python。
- 在 Add license 选择列表中选择您喜欢的许可证。MDN 在此示例中使用了“Creative Commons Zero v1.0 Universal”。
- 勾选 Initialize this repository with a README。
按下 Create repository。

仓库将被创建，只包含 README.txt 和 .gitignore 文件。

将仓库克隆到您的本地计算机

现在仓库（“repo”）已在 GitHub 上创建，我们希望将其克隆（复制）到我们的本地计算机

在 GitHub 上，点击绿色的 Code 按钮。在“Clone”部分，选择“HTTPS”选项卡，然后复制 URL。如果您使用的仓库名称是“django_local_library”，则 URL 应该类似于：https://github.com/<your_git_user_id>/django_local_library.git。
为您的本地计算机安装 git（官方 Git 下载指南）。
打开命令提示符/终端，并使用您上面复制的 URL 克隆您的仓库
bash
```
git clone https://github.com/<your_git_user_id>/django_local_library.git
```
这将在当前目录中创建仓库。
导航到仓库文件夹。
bash
```
cd django_local_library
```

修改并同步更改

现在我们将修改本地计算机上的 .gitignore 文件，提交更改，并更新 GitHub 上的仓库。这是一个有用的更改，但我们主要这样做是为了向您展示如何从 GitHub 拉取更改，在本地进行更改，然后将它们推送到 GitHub。

在命令提示符/终端中，我们首先“fetch”（获取）然后 pull（获取并合并到当前分支）来自 GitHub 的最新版本源代码

注意：此步骤并非绝对必要，因为我们刚刚克隆了源代码，并且知道它是最新的。但通常情况下，您应该在进行更改之前从 GitHub 更新您的源代码。
bash
```
git fetch origin main
git pull origin main
```
“origin”是一个远程，它代表源代码仓库的位置，“main”是分支。您可以使用命令：git remote -v 来验证 origin 是我们在 GitHub 上的仓库。
接下来，我们检出一个新分支来存储我们的更改
bash
```
git checkout -b update_gitignore
```
checkout 命令用于将某个分支切换为当前正在工作的分支。-b 标志表示我们打算创建一个名为“update_gitignore”的新分支，而不是选择一个同名现有分支。
打开 .gitignore 文件，将以下行复制到其底部，然后保存
```
# Text backup files
*.bak

# Database
*.sqlite3
```
请注意，.gitignore 用于指示不应由 git 自动备份的文件，例如临时文件和其他构建工件。
使用 add 命令将所有已更改的文件（未被 .gitignore 文件忽略的文件）添加到当前分支的“暂存区”。
bash
```
git add -A
```
使用 status 命令检查您即将 commit 的所有文件是否正确（您希望包含源文件，而不是二进制文件、临时文件等）。它应该看起来有点像下面的列表。
bash
```
> git status
On branch main
Your branch is up-to-date with 'origin/update_gitignore'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   .gitignore
```
当您满意时，使用 -m 标志将文件 commit 到您的本地仓库，并指定一个简洁明了的提交消息。这相当于签署更改并使其成为本地仓库的正式部分。
bash
```
git commit -m ".gitignore: add .bak and .sqlite3"
```
此时，远程仓库尚未更改。我们可以使用以下命令将 update_gitignore 分支推送到“origin”仓库（GitHub）
bash
```
git push origin update_gitignore
```
返回您在 GitHub 上创建仓库的页面并刷新页面。

应该会出现一个横幅，其中带有一个按钮，如果您想“比较并拉取请求”您刚刚上传的分支，则可以按下该按钮。选择该按钮，然后按照说明创建并合并拉取请求。

合并后，GitHub 上仓库的“main”分支将包含您对 .gitignore 的更改。
您可以使用此 add/commit/push 循环继续更新您的本地仓库，因为文件会更改。

在下一个主题中，我们将使用此仓库来存储我们的本地图书馆网站源代码。

其他 Python 工具

经验丰富的 Python 开发人员可能会安装其他工具，例如 linters（有助于检测代码中的常见错误）。

请注意，您应该使用支持 Django 的 linter，例如 pylint-django，因为一些常见的 Python linters（例如 pylint）会错误地报告 Django 生成的标准文件中的错误。

测试您的安装

上面的测试有效，但它并没有太多乐趣。一个更有趣的测试是创建一个骨架项目并观察它的运行情况。为此，首先在您的命令提示符/终端中导航到您想要存储 Django 应用程序的位置。为您的测试站点创建一个文件夹并导航到其中。

bash

mkdir django_test
cd django_test

然后，您可以使用 django-admin 工具创建一个名为“mytestsite”的新骨架站点，如所示。创建站点后，您可以导航到文件夹，在那里您将找到管理项目的主要脚本，名为 manage.py。

bash

django-admin startproject mytestsite
cd mytestsite

我们可以使用 manage.py 和 runserver 命令在此文件夹中运行开发 Web 服务器，如所示。

bash

# Linux/macOS
python3 manage.py runserver

# Windows
py -3 manage.py runserver

注意：此时您可以忽略关于“未应用的迁移”的警告！

服务器运行后，您可以通过在本地 Web 浏览器中导航到以下 URL 来查看站点：http://127.0.0.1:8000/。您应该会看到一个如下所示的站点

The home page of the skeleton Django app

总结

您现在已经在计算机上运行了 Django 开发环境。

在测试部分，您还简要了解了如何使用 django-admin startproject 创建一个新的 Django 网站，并使用开发 Web 服务器 (python3 manage.py runserver) 在浏览器中运行它。在下一篇文章中，我们将在此过程的基础上，构建一个简单但完整的 Web 应用程序。

另见

快速安装指南 (Django 文档)
如何安装 Django — 完整指南 (Django 文档) — 也涵盖了如何卸载 Django
如何在 Windows 上安装 Django (Django 文档)

帮助改进 MDN

了解如何贡献

本页面最后修改于 2025 年 6 月 23 日，由 MDN 贡献者修订。

在 GitHub 上查看此页面 • 报告此内容的问题