matplotlib · scottshambaugh · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
diff --git a/.github/workflows/dev_build.yml b/.github/workflows/dev_build.yml
@@ -0,0 +1,124 @@
+---
+# Exercises the documented build paths from doc/devel/development_setup.rst.
+name: Dev builds
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - main
+      - v[0-9]+.[0-9]+.x
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    permissions:
+      contents: read
+    name: "Dev builds on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    defaults:
+      run:
+        # Login shell so the conda environment can be activated in its step.
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0  # full history so setuptools-scm can determine the version
+          persist-credentials: false
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+        with:
+          enable-cache: true
+
+      - uses: mamba-org/setup-micromamba@d7c9bd84e824b79d2af72a2d4196c7f4300d3476  # v3.0.0
+        with:
+          init-shell: bash
+          cache-downloads: true
+
+      - name: Build with venv + pip
+        id: venv_pip
+        continue-on-error: true
+        run: |
+          rm -rf build
+          python -m venv .venv-pip
+          source .venv-pip/bin/activate 2>/dev/null || source .venv-pip/Scripts/activate
+          python -m pip install -U pip
+          python -m pip install --group dev
+          # Strawberry Perl's gcc on PATH shadows MSVC, so --vsenv forces MSVC.
+          VSENV=()
+          [ "$RUNNER_OS" = Windows ] && VSENV=(--config-settings=setup-args=--vsenv)
+          python -m pip install --verbose --no-build-isolation --group dev "${VSENV[@]}" --editable .
+          python -c "import matplotlib; print(matplotlib.__file__, matplotlib.__version__)"
+
+      - name: Build with conda + pip
+        id: conda
+        continue-on-error: true
+        run: |
+          rm -rf build
+          # Create the env here rather than via setup-micromamba's
+          # environment-file input, which crashes on environment.yml's
+          # nbconvert[execute] spec.
+          micromamba create -y -n mpl-dev -f environment.yml
+          micromamba activate mpl-dev
+          # conda's MSVC setup doesn't run under bash, so --vsenv forces MSVC.
+          VSENV=()
+          [ "$RUNNER_OS" = Windows ] && VSENV=(--config-settings=setup-args=--vsenv)
+          python -m pip install --verbose --no-build-isolation --group dev "${VSENV[@]}" --editable .
+          python -c "import matplotlib; print(matplotlib.__file__, matplotlib.__version__)"
+
+      - name: Build with uv pip
+        id: uv_pip
+        continue-on-error: true
+        run: |
+          rm -rf build
+          uv venv --python 3.13 .venv-uvpip
+          source .venv-uvpip/bin/activate 2>/dev/null || source .venv-uvpip/Scripts/activate
+          uv pip install --group dev
+          VSENV=()
+          [ "$RUNNER_OS" = Windows ] && VSENV=(-C setup-args=--vsenv)
+          uv pip install --verbose --no-build-isolation --group dev "${VSENV[@]}" --editable .
+          python -c "import matplotlib; print(matplotlib.__file__, matplotlib.__version__)"
+
+      - name: Build with uv sync
+        id: uv_sync
+        continue-on-error: true
+        env:
+          UV_PROJECT_ENVIRONMENT: .venv-uvsync
+        run: |
+          rm -rf build
+          # Build separately without isolation, since meson-python editable breaks if
+          # its build env is deleted.
+          uv sync --python 3.13 --group dev --no-install-project
+          source .venv-uvsync/bin/activate 2>/dev/null || source .venv-uvsync/Scripts/activate
+          VSENV=()
+          [ "$RUNNER_OS" = Windows ] && VSENV=(-C setup-args=--vsenv)
+          uv pip install --verbose --no-build-isolation --group dev "${VSENV[@]}" --editable .
+          python -c "import matplotlib; print(matplotlib.__file__, matplotlib.__version__)"
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "venv + pip : ${{ steps.venv_pip.outcome }}"
+          echo "conda      : ${{ steps.conda.outcome }}"
+          echo "uv pip     : ${{ steps.uv_pip.outcome }}"
+          echo "uv sync    : ${{ steps.uv_sync.outcome }}"
+          test "${{ steps.venv_pip.outcome }}" = success \
+            && test "${{ steps.conda.outcome }}" = success \
+            && test "${{ steps.uv_pip.outcome }}" = success \
+            && test "${{ steps.uv_sync.outcome }}" = success
diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst
@@ -141,6 +141,7 @@ setup.
 
 .. _venv: https://docs.python.org/3/library/venv.html
 .. _conda: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
+.. _uv: https://docs.astral.sh/uv/
 
 .. tab-set::
 
@@ -182,6 +183,59 @@ setup.
 
       Remember to activate the environment whenever you start working on Matplotlib!
 
+   .. tab-item:: uv environment
+
+      `uv`_ is a fast drop-in replacement for ``pip`` and ``venv``. After
+      `installing uv <https://docs.astral.sh/uv/getting-started/installation/>`_,
+      create a new environment and install the Python dependencies with ::
+
+        uv venv
+        uv pip install --group dev
+
+      and activate it with one of the following :
+
+      .. tab-set::
+
+         .. tab-item:: Linux and macOS
+
+            .. code-block:: bash
+
+               source .venv/bin/activate
+
+         .. tab-item:: Windows cmd.exe
+
+            .. code-block:: bat
+
+               .venv\Scripts\activate.bat
+
+         .. tab-item:: Windows PowerShell
+
+            .. code-block:: ps1con
+
+               .venv\Scripts\Activate.ps1
+
+      Remember to activate the environment whenever you start working on Matplotlib!
+
+      .. note::
+
+         When using uv, prefix the remaining ``pip`` commands in this guide with
+         ``uv``. For example, the :ref:`editable install <development-install>`
+         below becomes ::
+
+            uv pip install --verbose --no-build-isolation --group dev --editable .
+
+         You can also manage the environment from a lockfile with ``uv sync``.
+         Because Matplotlib has a compiled (meson-python) build, install the
+         dependencies and the editable build in separate steps ::
+
+            uv sync --group dev --no-install-project
+            uv pip install --no-build-isolation --no-deps --editable .
+
+         Then activate the environment as above. Avoid ``uv run``, because it
+         re-syncs the project and rebuilds the editable install with build
+         isolation, which is incompatible with the meson-python editable rebuild.
+         ``uv run --no-sync`` will work around this.
+
    .. tab-item:: conda environment
 
       Create a new `conda`_ environment and install the Python dependencies with ::