:bug: Installation failure on macOS

[wjrforcyber]

Hi!
I keep seeing this on
macOS 15.3.2
uv 0.6.14 (a4cec56dc 2025-04-09)
I search for a bit and it seems an old problem which has workaround but no fix, check the thread here.

uv sync                  
Resolved 126 packages in 5ms
  × Failed to build `pygraphviz==1.14`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)

      [stdout]
      running bdist_wheel
      running build
      running build_py
      copying pygraphviz/scraper.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/graphviz.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/__init__.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/agraph.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/testing.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/tests/test_unicode.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_scraper.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_readwrite.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_string.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/__init__.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_html.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_node_attributes.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_drawing.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_repr_mimebundle.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_subgraph.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_close.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_edge_attributes.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_clear.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_layout.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_attribute_defaults.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_graph.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
     ...
     ...
     ...
      pygraphviz/graphviz_wrap.c:9:9: warning: 'SWIG_PYTHON_STRICT_BYTE_CHAR' macro redefined [-Wmacro-redefined]
          9 | #define SWIG_PYTHON_STRICT_BYTE_CHAR
            |         ^
      <command line>:2:9: note: previous definition is here
          2 | #define SWIG_PYTHON_STRICT_BYTE_CHAR 1
            |         ^
      pygraphviz/graphviz_wrap.c:3023:10: fatal error: 'graphviz/cgraph.h' file not found
       3023 | #include "graphviz/cgraph.h"
            |          ^~~~~~~~~~~~~~~~~~~
      1 warning and 1 error generated.
      error: command '/usr/bin/cc' failed with exit code 1

      hint: This error likely indicates that you need to install a library that provides "graphviz/cgraph.h" for
      `pygraphviz@1.14`
  help: `pygraphviz` (v1.14) was included because `aigverse:dev` depends on `pygraphviz`

Probably need to give an instruction on this when install on Mac(I only see relevant issues on Mac so far)?
Since pip does allow virtual environments to access global package using --system-site-packages(although not recommended) but I'm not an expert in uv, so even if I would like to use the bypass method it's not quite easy, is there a simple way to separate graphviz out?

[marcelwa]

Thank you for reporting the issue! I will look into it.

In the meantime, may I ask about your use case? That would enable for a quick workaround while I work on a permanent solution.

pygraphviz is only needed if you want to build the documentation. If you're okay just building the library locally, you can try

uv pip install . -E build

which installs the build dependencies exclusively and builds the project.

If you're only interested in using aigverse, I'd recommend installing it from PyPI via

uv pip install aigverse

[wjrforcyber]

Thanks! I noticed it's only in doc.
The use case is I find this project interesting but do lack of some interface in mockturtle and I am trying to get familiar with every section of it, and if possible, add the interface I need.
Currently I install with uv sync --no-install-package pygraphviz and every build/test/doc works fine except some block in documentation break.
Bring this up in case anyone on macOS has managed to get a preview of documentation locally.

[marcelwa]

I see, thanks for clarifying. I'm glad your workaround helps for now. As said, I'm going to look into a more permanent solution.

Since this project is still in its early stages, any help exposing more of mockturtle's functionality is welcome and highly appreciated!

[marcelwa]

@wjrforcyber I've added additional documentation to inform users to manually install Graphviz before attempting to build the documentation. Also, I've added a check to nox -s docs to test for the existence of Graphviz before installing pygraphviz. Does this address your concerns?

[wjrforcyber]

@wjrforcyber I've added additional documentation to inform users to manually install Graphviz before attempting to build the documentation. Also, I've added a check to nox -s docs to test for the existence of Graphviz before installing pygraphviz. Does this address your concerns?

The warning is good point and I appreciate your time on this.

As I mentioned above uv sync --no-install-package pygraphviz could give developer a successfully built doc with some break sections.

The key point is, even if I manually installed the pygraphviz package globally with workaround mention above, it only takes effect when the virtual environment can have access to the global package with workaround here, which I used venv with --system-site-packages.(which is a really bad idea), and installed all the packages in toml file's docs section without pygraphviz.
With the above method I have made it worked and the sections with pics are shown properly now, but the process is quite complicated, let's hope someone in the future could give a more convenient way. 😅

[marcelwa]

Unfortunately, I don't have a macOS machine available to test this better locally, but installing pygraphviz from PyPI should work if you installed Graphviz from Homebrew before. It would be great if you could confirm that

brew install graphviz
uvx nox -s docs

generates a valid documentation.

[wjrforcyber]

Nope, it fails on build the pygraphviz actually in the uvx nox -s docs, the wheel is failed to build. I paste the whole log here in case you want to see the details:

➜  aigverse git:(testdoc) ✗ git log --oneline -1 | cat
7877b1b ✨ Add `FanoutAig` that implements `mockturtle::fanout_view` (#116)
➜  aigverse git:(testdoc) ✗ brew deps --tree --installed | grep graphviz   
graphviz
➜  aigverse git:(testdoc) ✗ uvx nox -s docs                                
nox > Running session docs
nox > Re-using existing virtual environment at .nox/docs.
nox > uv pip install sphinx-autobuild
nox > uv sync --inexact --only-group build --only-group docs
Resolved 126 packages in 0.89ms
  × Failed to build `pygraphviz==1.14`
  ├─▶ The build backend returned an error
  ╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)

      [stdout]
      running bdist_wheel
      running build
      running build_py
      copying pygraphviz/scraper.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/graphviz.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/__init__.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/agraph.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/testing.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/tests/test_unicode.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_scraper.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_readwrite.py ->
      build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_string.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/__init__.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_html.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_node_attributes.py ->
      build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_drawing.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_repr_mimebundle.py ->
      build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_subgraph.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_close.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_edge_attributes.py ->
      build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_clear.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_layout.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_attribute_defaults.py ->
      build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      copying pygraphviz/tests/test_graph.py -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz/tests
      running egg_info
      writing pygraphviz.egg-info/PKG-INFO
      writing dependency_links to pygraphviz.egg-info/dependency_links.txt
      writing top-level names to pygraphviz.egg-info/top_level.txt
      reading manifest file 'pygraphviz.egg-info/SOURCES.txt'
      reading manifest template 'MANIFEST.in'
      adding license file 'LICENSE'
      writing manifest file 'pygraphviz.egg-info/SOURCES.txt'
      copying pygraphviz/graphviz.i -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      copying pygraphviz/graphviz_wrap.c -> build/lib.macosx-11.0-arm64-cpython-312/pygraphviz
      running build_ext
      building 'pygraphviz._graphviz' extension
      cc -fno-strict-overflow -Wsign-compare -Wunreachable-code -DNDEBUG -g -O3 -Wall -arch arm64
      -mmacosx-version-min=11.0 -Wno-nullability-completeness -Wno-expansion-to-defined -Wno-undef-prefix
      -fPIC -DSWIG_PYTHON_STRICT_BYTE_CHAR -I/Users/jingrenwang/.cache/uv/builds-v0/.tmpmwUUy1/include
      -I/Users/jingrenwang/.local/share/uv/python/cpython-3.12.10-macos-aarch64-none/include/python3.12 -c
      pygraphviz/graphviz_wrap.c -o build/temp.macosx-11.0-arm64-cpython-312/pygraphviz/graphviz_wrap.o

      [stderr]
      /Users/jingrenwang/.cache/uv/builds-v0/.tmpmwUUy1/lib/python3.12/site-packages/setuptools/config/_apply_pyprojecttoml.py:82:
      SetuptoolsDeprecationWarning: `project.license` as a TOML table is deprecated
      !!

              ********************************************************************************
              Please use a simple string containing a SPDX expression for `project.license`. You can also
      use `project.license-files`. (Both options available on setuptools>=77.0.0).

              By 2026-Feb-18, you need to update your project and remove deprecated calls
              or your builds will no longer be supported.

              See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for
      details.
              ********************************************************************************

      !!
        corresp(dist, value, root_dir)
      /Users/jingrenwang/.cache/uv/builds-v0/.tmpmwUUy1/lib/python3.12/site-packages/setuptools/config/_apply_pyprojecttoml.py:61:
      SetuptoolsDeprecationWarning: License classifiers are deprecated.
      !!

              ********************************************************************************
              Please consider removing the following classifiers in favor of a SPDX license expression:

              License :: OSI Approved :: BSD License

              See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for
      details.
              ********************************************************************************

      !!
        dist._finalize_license_expression()
      /Users/jingrenwang/.cache/uv/builds-v0/.tmpmwUUy1/lib/python3.12/site-packages/setuptools/dist.py:759:
      SetuptoolsDeprecationWarning: License classifiers are deprecated.
      !!

              ********************************************************************************
              Please consider removing the following classifiers in favor of a SPDX license expression:

              License :: OSI Approved :: BSD License

              See https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#license for
      details.
              ********************************************************************************

      !!
        self._finalize_license_expression()
      warning: no files found matching '*.swg'
      warning: no files found matching '*.png' under directory 'doc'
      warning: no files found matching '*.html' under directory 'doc'
      warning: no files found matching '*.txt' under directory 'doc'
      warning: no files found matching '*.css' under directory 'doc'
      warning: no previously-included files matching '*~' found anywhere in distribution
      warning: no previously-included files matching '*.pyc' found anywhere in distribution
      warning: no previously-included files matching '.svn' found anywhere in distribution
      no previously-included directories found matching 'doc/build'
      pygraphviz/graphviz_wrap.c:9:9: warning: 'SWIG_PYTHON_STRICT_BYTE_CHAR' macro redefined
      [-Wmacro-redefined]
          9 | #define SWIG_PYTHON_STRICT_BYTE_CHAR
            |         ^
      <command line>:2:9: note: previous definition is here
          2 | #define SWIG_PYTHON_STRICT_BYTE_CHAR 1
            |         ^
      pygraphviz/graphviz_wrap.c:3023:10: fatal error: 'graphviz/cgraph.h' file not found
       3023 | #include "graphviz/cgraph.h"
            |          ^~~~~~~~~~~~~~~~~~~
      1 warning and 1 error generated.
      error: command '/usr/bin/cc' failed with exit code 1

      hint: This error likely indicates that you need to install a library that provides
      "graphviz/cgraph.h" for `pygraphviz@1.14`
  help: `pygraphviz` (v1.14) was included because `aigverse:docs` depends on `pygraphviz`
nox > Command uv sync --inexact --only-group build --only-group docs failed with exit code 1
nox > Session docs failed.

[marcelwa]

Thanks for confirming. I reopened the issue and will look into alternative solutions.