设置 Matplotlib 进行开发#

要为 Matplotlib 设置开发环境，请按照以下步骤操作：

Fork Matplotlib 仓库#

Matplotlib 托管在 matplotlib/matplotlib.git。如果你计划解决 Matplotlib 主仓库的问题或提交拉取请求，你应该首先通过访问 matplotlib/matplotlib.git 并点击页面右上角的 Fork 按钮来 fork 这个仓库。更多详情请参阅 GitHub 文档。

获取代码的最新版本#

现在，你的仓库分支已经存在于你的GitHub用户名下，你可以使用以下命令之一来获取源代码的最新版本（将 <your-username> 替换为你的GitHub用户名）：

git clone https://github.com/<your-username>/matplotlib.git

git clone git@github.com:<your-username>/matplotlib.git

这要求你提前设置一个 SSH 密钥，但可以让你在每次连接时无需输入密码。

这会将源代码放置在当前工作目录下的 matplotlib 目录中，并将远程名称 origin 指向您的分支。在继续之前，请切换到此目录:

cd matplotlib

现在将远程名称 upstream 指向 Matplotlib 主仓库：

git remote add upstream https://github.com/matplotlib/matplotlib.git

git remote add upstream git@github.com:matplotlib/matplotlib.git

你现在可以使用 upstream 来获取源代码的最新快照，如 开发工作流程 中所述。

额外的 git 和 GitHub 资源

有关 git 和 GitHub 的更多信息，请参见：

创建一个专用环境#

你应该设置一个专门的环境，以将你的 Matplotlib 开发与系统上的其他 Python 和 Matplotlib 安装解耦。

最简单的方法是使用 Python 的虚拟环境 venv 或 conda。

使用 :: 创建一个新的 venv 环境

python -m venv <file folder location>

并通过以下方式之一激活它

source <file folder location>/bin/activate  # Linux/macOS
<file folder location>\Scripts\activate.bat  # Windows cmd.exe
<file folder location>\Scripts\Activate.ps1  # Windows PowerShell

在某些系统上，您可能需要输入 python3 而不是 python。关于技术原因的讨论，请参见 PEP-394。

使用以下命令安装 Python 依赖项

pip install -r requirements/dev/dev-requirements.txt

创建一个新的 conda 环境，并使用以下命令安装Python依赖项：：

conda env create -f environment.yml

如果你安装了 mamba ，你可以在上面的命令中使用 mamba 代替 conda。

使用以下命令激活环境

conda activate mpl-dev

每当你开始在 Matplotlib 上工作时，记得激活环境。

安装依赖项#

大多数 Python 依赖项将在 设置环境 时安装，但像 C++ 编译器、LaTeX 和其他系统应用程序这样的非 Python 依赖项必须单独安装。

以可编辑模式安装 Matplotlib#

使用以下命令从 matplotlib 目录以可编辑模式安装 Matplotlib

python -m pip install --verbose --no-build-isolation --editable ".[dev]"

‘可编辑/开发模式’会构建所有内容，并在您的Python环境中放置链接，以便Python能够从您的开发源目录导入Matplotlib。这使您可以在修改 .py 或编译扩展文件后，无需重新安装即可导入修改后的Matplotlib版本。

当在一个未启用 Meson 的分支上工作时，即其历史（日志）中没有 PR #26621，每次更改任何编译扩展代码时，你都必须从源代码重新安装。

如果安装不成功，请查阅 故障排除指南 。如果指南没有提供解决方案，请通过 聊天 或 提交问题 联系我们。

构建选项#

如果你在处理需要编译的文件，你可能想要检查编译日志。这可以通过设置环境变量 MESONPY_EDITABLE_VERBOSE 或在安装时设置 editable-verbose 配置来启用

python -m pip install --no-build-isolation --config-settings=editable-verbose=true --editable .

有关安装和其他配置选项的更多信息，请参阅 Meson Python 可编辑安装指南。

要查看在安装前可以设置的其他环境变量的列表，请参阅 环境变量。

验证安装#

运行以下命令以确保您已正确安装了可编辑模式的 Matplotlib。该命令应在激活虚拟环境时运行:

python -c "import matplotlib; print(matplotlib.__file__)"

此命令应返回： <matplotlib_local_repo>\lib\matplotlib\__init__.py

我们鼓励您运行测试并构建文档，以验证代码是否正确安装以及文档是否干净构建，这样当您进行代码或文档相关更改时，您可以事先了解现有问题。

  • 运行测试用例以验证安装 测试

  • 验证文档构建 记录matplotlib

安装预提交钩子#

pre-commit 钩子通过在正式提交拉取请求之前识别代码中的问题，从而节省了审查过程中的时间。大多数钩子还可以帮助修复错误，并且这些检查应具有相应的 开发工作流程 和 拉取请求 指南。钩子在 .pre-commit-config.yaml 中配置，并包括拼写和格式检查、flake 8 合规性、意外提交的文件、导入顺序和错误的分支检查。

安装预提交钩子

python -m pip install pre-commit
pre-commit install

钩子在 编辑工作流程 的 git commit 阶段后自动运行。当一个钩子发现并修复了文件中的错误时，该文件必须再次 暂存并提交。

钩子也可以手动运行。所有钩子可以按照 .pre-commit-config.yaml 中的顺序，针对整个代码库运行，使用

pre-commit run --all-files

要手动运行特定钩子，请使用钩子ID运行 pre-commit run

pre-commit run <hook id> --all-files

请注意，mypy 预提交钩子无法检查新函数的 类型提示 ；相反，新函数的存根使用 stubtest CI 检查 进行检查，并且可以使用 tox -e stubtest 在本地进行检查。

On this page