<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP12.html">MEP12: Improve Gallery and Examples</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP13.html">MEP13: Use properties for Artists</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP14.html">MEP14: Text handling</a></li>
<liclass="toctree-l2"><aclass="reference internal" href="MEP/MEP15.html">MEP15: Fix axis autoscaling when limits are specified for one axis only</a></li>
<h2><aclass="toc-backref" href="#id1" role="doc-backlink">Fork the Matplotlib repository</a><aclass="headerlink" href="#fork-the-matplotlib-repository" title="Link to this heading">#</a></h2>
<p>Matplotlib is hosted at <aclass="github reference external" href="https://github.com/matplotlib/matplotlib.git">matplotlib/matplotlib.git</a>. If you
plan on solving issues or submitting pull requests to the main Matplotlib
repository, you should first fork this repository by <em>clicking</em> the
<p>This creates a copy of the code under your account on the GitHub server. See <aclass="reference external" href="https://docs.github.com/get-started/quickstart/fork-a-repo">the GitHub
documentation</a> for more details.</p>
</section>
<sectionid="set-up-development-environment">
<h2><aclass="toc-backref" href="#id2" role="doc-backlink">Set up development environment</a><aclass="headerlink" href="#set-up-development-environment" title="Link to this heading">#</a></h2>
<p>You can either work locally on your machine, or online in
<aclass="reference external" href="https://docs.github.com/codespaces">GitHub Codespaces</a>, a cloud-based in-browser development
<ddclass="field-even"><p>If you are making a one-off, relatively simple, change then working in
GitHub Codespaces can be a good option because most of the setting
up is done for you and you can skip the next few sections.</p>
</dd>
</dl>
<p>If you want to use Codespaces, skip to <aclass="reference internal" href="#development-codespaces"><spanclass="std std-ref">Create GitHub Codespace </span></a>,
otherwise, continue with the next section.</p>
<sectionid="create-local-environment">
<h3><aclass="toc-backref" href="#id3" role="doc-backlink">Create local environment</a><aclass="headerlink" href="#create-local-environment" title="Link to this heading">#</a></h3>
<sectionid="get-most-recent-code">
<h4><aclass="toc-backref" href="#id4" role="doc-backlink">Get most recent code</a><aclass="headerlink" href="#get-most-recent-code" title="Link to this heading">#</a></h4>
<p>Now that your fork of the repository lives under your GitHub username, you can
retrieve the most recent version of the source code with one of the following
commands (replace <codeclass="docutils literal notranslate"><spanclass="pre"><your-username></span></code> with your GitHub username):</p>
<p>This requires you to setup an <aclass="reference external" href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh">SSH key</a> in advance, but saves you from
typing your password at every connection.</p>
</div>
</div>
<p>This will place the sources in a directory <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlib</span></code> below your
current working directory and set the remote name <codeclass="docutils literal notranslate"><spanclass="pre">origin</span></code> to point to your
fork. Change into this directory before continuing:</p>
<p>Now set the remote name <codeclass="docutils literal notranslate"><spanclass="pre">upstream</span></code> to point to the Matplotlib main repository:</p>
<p>You can now use <codeclass="docutils literal notranslate"><spanclass="pre">upstream</span></code> to retrieve the most current snapshot of the source
code, as described in <aclass="reference internal" href="development_workflow.html#development-workflow"><spanclass="std std-ref">Development workflow</span></a>.</p>
<pclass="sd-card-text">For more information on <codeclass="docutils literal notranslate"><spanclass="pre">git</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">GitHub</span></code>, see:</p>
<li><pclass="sd-card-text"><aclass="reference external" href="https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project">GitHub-Contributing to a Project</a></p></li>
<spanid="dev-environment"></span><h4><aclass="toc-backref" href="#id5" role="doc-backlink">Create a dedicated environment</a><aclass="headerlink" href="#create-a-dedicated-environment" title="Link to this heading">#</a></h4>
<p>You should set up a dedicated environment to decouple your Matplotlib
development from other Python and Matplotlib installations on your system.</p>
<p>We recommend using one of the following options for a dedicated development environment
because these options are configured to install the Python dependencies as part of their
<p>On some systems, you may need to type <codeclass="docutils literal notranslate"><spanclass="pre">python3</span></code> instead of <codeclass="docutils literal notranslate"><spanclass="pre">python</span></code>.
For a discussion of the technical reasons, see <aclass="reference external" href="https://peps.python.org/pep-0394">PEP-394</a>.</p>
<p>Install the Python dependencies with</p>
<divclass="highlight-bash notranslate"><divclass="highlight"><pre><span></span>pip<spanclass="w"></span>install<spanclass="w"></span>-U<spanclass="w"></span>pip<spanclass="w"></span><spanclass="c1"># You may skip this step if pip 25.1 is already available.</span>
<p>Create a new <aclass="reference external" href="https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html">conda</a> environment and install the Python dependencies with</p>
<p>You can use <codeclass="docutils literal notranslate"><spanclass="pre">mamba</span></code> instead of <codeclass="docutils literal notranslate"><spanclass="pre">conda</span></code> in the above command if
you have <aclass="reference external" href="https://mamba.readthedocs.io/en/latest/">mamba</a> installed.</p>
<p>Remember to activate the environment whenever you start working on Matplotlib!</p>
</div>
</div>
</section>
<sectionid="install-external-dependencies">
<h4><aclass="toc-backref" href="#id6" role="doc-backlink">Install external dependencies</a><aclass="headerlink" href="#install-external-dependencies" title="Link to this heading">#</a></h4>
<p>Python dependencies were installed as part of <aclass="reference internal" href="#dev-environment"><spanclass="std std-ref">setting up the environment</span></a>.
Additionally, the following non-Python dependencies must also be installed locally:</p>
<ulclass="checklist simple">
<li><p><aclass="reference internal" href="../install/dependencies.html#compile-build-dependencies"><spanclass="std std-ref">Compilers and external build tools</span></a></p></li>
<li><p><aclass="reference internal" href="../install/dependencies.html#doc-dependencies-external"><spanclass="std std-ref">external tools used by the documentation build</span></a></p></li>
</ul>
<p>For a full list of dependencies, see <aclass="reference internal" href="../install/dependencies.html#dependencies"><spanclass="std std-ref">Dependencies</span></a>. External dependencies do not
need to be installed when working in codespaces.</p>
<p>Remember to activate the <em>mpl-dev</em> environment whenever you start working on
Matplotlib.</p>
<p>If you need to open a GUI window with Matplotlib output on Codespaces, our
configuration includes a <aclass="reference external" href="https://github.com/devcontainers/features/tree/main/src/desktop-lite">light-weight Fluxbox-based desktop</a>.
You can use it by connecting to this desktop via your web browser. To do this:</p>
<olclass="arabic simple">
<li><p>Press <codeclass="docutils literal notranslate"><spanclass="pre">F1</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">Ctrl/Cmd+Shift+P</span></code> and select
<codeclass="docutils literal notranslate"><spanclass="pre">Ports:</span><spanclass="pre">Focus</span><spanclass="pre">on</span><spanclass="pre">Ports</span><spanclass="pre">View</span></code> in the VSCode session to bring it into
focus. Open the ports view in your tool, select the <codeclass="docutils literal notranslate"><spanclass="pre">noVNC</span></code> port, and
click the Globe icon.</p></li>
<li><p>In the browser that appears, click the Connect button and enter the desktop
password (<codeclass="docutils literal notranslate"><spanclass="pre">vscode</span></code> by default).</p></li>
</ol>
<p>Check the <aclass="reference external" href="https://github.com/devcontainers/features/tree/main/src/desktop-lite#connecting-to-the-desktop">GitHub instructions</a>
for more details on connecting to the desktop.</p>
<p>If you also built the documentation pages, you can view them using Codespaces.
Use the "Extensions" icon in the activity bar to install the "Live Server"
extension. Locate the <codeclass="docutils literal notranslate"><spanclass="pre">doc/build/html</span></code> folder in the Explorer, right click
the file you want to open and select "Open with Live Server."</p>
</section>
</section>
<sectionid="install-matplotlib-in-editable-mode">
<spanid="development-install"></span><h2><aclass="toc-backref" href="#id8" role="doc-backlink">Install Matplotlib in editable mode</a><aclass="headerlink" href="#install-matplotlib-in-editable-mode" title="Link to this heading">#</a></h2>
<p>Install Matplotlib in editable mode from the <codeclass="file docutils literal notranslate"><spanclass="pre">matplotlib</span></code> directory using the
<p>The 'editable/develop mode' builds everything and places links in your Python environment
so that Python will be able to import Matplotlib from your development source directory.
This allows you to import your modified version of Matplotlib without having to
re-install after changing a <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> or compiled extension file.</p>
<p>When working on a branch that does not have Meson enabled, meaning it does not
have <aclass="reference external" href="https://github.com/matplotlib/matplotlib/pull/26621/">PR #26621</a> in its history (log), you will have to reinstall from source
each time you change any compiled extension code.</p>
<p>If the installation is not working, please consult the <aclass="reference internal" href="troubleshooting.html#troubleshooting-faq"><spanclass="std std-ref">troubleshooting guide</span></a>.
If the guide does not offer a solution, please reach out via <aclass="reference external" href="https://discourse.matplotlib.org">discourse</a>
or <aclass="reference internal" href="index.html#submitting-a-bug-report"><spanclass="std std-ref">open an issue</span></a>.</p>
<sectionid="build-options">
<h3><aclass="toc-backref" href="#id9" role="doc-backlink">Build options</a><aclass="headerlink" href="#build-options" title="Link to this heading">#</a></h3>
<p>If you are working heavily with files that need to be compiled, you may want to
inspect the compilation log. This can be enabled by setting the environment
variable <spanclass="target" id="index-0"></span><aclass="reference external" href="https://mesonbuild.com/meson-python/reference/environment-variables.html#envvar-MESONPY_EDITABLE_VERBOSE" title="(in meson-python)"><codeclass="xref std std-envvar docutils literal notranslate"><spanclass="pre">MESONPY_EDITABLE_VERBOSE</span></code></a> or by setting the <codeclass="docutils literal notranslate"><spanclass="pre">editable-verbose</span></code>
<p>For a list of the other environment variables you can set before install, see <aclass="reference internal" href="../install/environment_variables_faq.html#environment-variables"><spanclass="std std-ref">Environment variables</span></a>.</p>
</section>
</section>
<sectionid="verify-the-installation">
<h2><aclass="toc-backref" href="#id10" role="doc-backlink">Verify the Installation</a><aclass="headerlink" href="#verify-the-installation" title="Link to this heading">#</a></h2>
<p>Run the following command to make sure you have correctly installed Matplotlib in
editable mode. The command should be run when the virtual environment is activated:</p>
<p>This command should return : <codeclass="docutils literal notranslate"><spanclass="pre"><matplotlib_local_repo>\lib\matplotlib\__init__.py</span></code></p>
<p>We encourage you to run tests and build docs to verify that the code installed correctly
and that the docs build cleanly, so that when you make code or document related changes
you are aware of the existing issues beforehand.</p>
<ulclass="simple">
<li><p>Run test cases to verify installation <aclass="reference internal" href="testing.html#testing"><spanclass="std std-ref">Testing</span></a></p></li>
<spanid="pre-commit-hooks"></span><h2><aclass="toc-backref" href="#id11" role="doc-backlink">Install pre-commit hooks</a><aclass="headerlink" href="#install-pre-commit-hooks" title="Link to this heading">#</a></h2>
<p><aclass="reference external" href="https://prek.j178.dev/">prek</a> hooks save time in the review process by
identifying issues with the code before a pull request is formally opened. Most
hooks can also aide in fixing the errors, and the checks should have
corresponding <aclass="reference internal" href="development_workflow.html#development-workflow"><spanclass="std std-ref">development workflow</span></a> and
<aclass="reference internal" href="pr_guide.html#pr-guidelines"><spanclass="std std-ref">pull request</span></a> guidelines. Hooks are configured in
<p>Hooks are run automatically after the <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">commit</span></code> stage of the
<aclass="reference internal" href="development_workflow.html#edit-flow"><spanclass="std std-ref">editing workflow</span></a>. When a hook has found and fixed an error in a
file, that file must be <em>staged and committed</em> again.</p>
<p>Hooks can also be run manually. All the hooks can be run, in order as
listed in <codeclass="docutils literal notranslate"><spanclass="pre">.pre-commit-config.yaml</span></code>, against the full codebase with</p>
<p>To run a particular hook manually, run <codeclass="docutils literal notranslate"><spanclass="pre">prek</span><spanclass="pre">run</span></code> with the hook id</p>
<p>Please note that the <codeclass="docutils literal notranslate"><spanclass="pre">mypy</span></code> pre-commit hook cannot check the <aclass="reference internal" href="coding_guide.html#type-hints"><spanclass="std std-ref">Type hints</span></a>
for new functions; instead the stubs for new functions are checked using the
<codeclass="docutils literal notranslate"><spanclass="pre">stubtest</span></code><aclass="reference internal" href="development_workflow.html#automated-tests"><spanclass="std std-ref">CI check</span></a> and can be checked locally using