11

There have been several 'unanswered' postings on this topic pertaining finding 'sphinx-build' not being able to be found: sphinx-build -h command not found in Mac OS

Sphinx was installed upon OSX using both:

  • python3 -m pip install sphinx
  • brew install sphinx

In either case, both commands sphinx-build and sphinx-quickstart cannot be found.

Even though python3 -m pip freeze shows installation:

Sphinx==1.3.6

What am I missing?

Thx

Community
  • 1
  • 1
jeff00seattle
  • 1,291
  • 5
  • 17
  • 31

5 Answers5

30

For homebrew, the tools seem to be in sphinx-doc nowadays. And it's not by default put in your PATH either because sphinx-doc is "keg-only". To install it and get it into PATH, you can do:

brew install sphinx-doc
brew link sphinx-doc --force

For full disclosure to the reader, I will include the keg-only warning brew emits when --force is not used:

Warning: sphinx-doc is keg-only and must be linked with --force
Note that doing so can interfere with building software.

I don't know why sphinx-doc is keg-only, but putting sphinx-{quickstart,apidoc,autogen,build} in PATH seems harmless to me.

scode
  • 9,917
  • 2
  • 16
  • 5
  • 1
    I believe the reason that it gives you that warning is because `pip3 install sphinx` *also* wants to write to /usr/local/bin/spinx-apidoc` and so on. For example if you do `brew install sphinx-dox; pip3 install breathe;` the latter will fail because it tries to do `pip3 install sphinx` and can't overwrite `/usr/local/bin/sphinx-apidoc`. Although I guess the correct solution in this case is to uninstall brew's sphinx. – Timmmm Oct 27 '17 at 09:50
  • 1
    Although... now that I did that, `pip3 install sphinx` doesn't actually write to `/usr/local/bin/sphinx-apidoc`. It must have tried to do something else to it (I got a permission denied error). – Timmmm Oct 27 '17 at 09:52
  • 1
    After running `pip3 uninstall sphinx; pip3 install sphinx` all of the `sphinx-build` etc. scripts showed up. – Timmmm Oct 27 '17 at 10:07
12

I had a similar issue after installing sphinx on OS X El Capitan. I installed sphinx using pip: pip install sphinx --user. Despite the sphinx-build binary existing in ~/Library/Python/2.7/bin, the command could not be found.

The issue was that I had path set to PATH="~/Library/Python/2.7/bin:$PATH". Replacing the tilde ~ with $HOME so that it was PATH="$HOME/Library/Python/2.7/bin:$PATH" fixed the problem for me.

Dan Murphy
  • 236
  • 2
  • 3
  • This doesn't work if python was installed with homebrew, and the question does contain `brew install ...`, but its not explicit. – Julian Irwin Aug 27 '16 at 18:05
1

Following the suggestion of @Dan Murphy

My installation of python 3.4 was at root. Modified ~/.bash_profile as follows:

export PATH="/Library/Frameworks/Python.framework/Versions/3.4/bin/:$PATH"
Community
  • 1
  • 1
jeff00seattle
  • 1,291
  • 5
  • 17
  • 31
1

If you used homebrew to install Python the paths are slightly different. Here is what I hope is a general method for resolving this problem:

  • Run python3 -c 'import sys; print("\n".join(sys.path))' and look for some lines like .../Python.framework/Versions/3.5/lib/....

  • There will be a bin/ that is a sibling of lib/. That bin/ contains sphinx-quickstart and the other sphinx commands.

  • For homebrew installed python3 on osx the directory should be /usr/local/Cellar/python3/3.5.1/Frameworks/Python.framework/Versions/3.5/bin

  • Put export PATH=$PATH:.../Python.framework/Versions/3.5/bin in your bash profile and restart your terminal.

Julian Irwin
  • 172
  • 10
  • I couldn't find anything sphinx-related anywhere in that folder unfortunately. In fact `pip3 uninstall sphinx` lists all the files it will remove and there is no `sphinx-build` anywhere. – Timmmm Oct 27 '17 at 09:59
  • Weird - I uninstalled it and reinstalled it and the second time it correctly added scripts in /usr/local/bin – Timmmm Oct 27 '17 at 10:07
  • > *There will be a bin/ that is a sibling of*, I don't know what this is referring to, where is this supposed to be? – baxx Feb 05 '20 at 21:21
0

For new users, installing with brew gives the following caveats:

==> sphinx-doc
sphinx-doc is keg-only, which means it was not symlinked into /usr/local,
because this formula is mainly used internally by other formulae.
Users are advised to use `pip` to install sphinx-doc.

If you need to have sphinx-doc first in your PATH, run:
  echo 'export PATH="/usr/local/opt/sphinx-doc/bin:$PATH"' >> ~/.zshrc

Running the echo command:

echo 'export PATH="/usr/local/opt/sphinx-doc/bin:$PATH"' >> ~/.zshrc

should fix the issue.

Don't miss source-ing the .zshrc after the updating it:

source ~/.zshrc
Vaibhav Mishra
  • 415
  • 3
  • 10