title: Pip (python) differences between `--install-option='--prefix'` and `--root` and `--target`
body: <p>The <a href="http://pip.readthedocs.org/en/latest/"><code>pip</code> documentation</a> lacks too much wordings (to my eyes), about parameters to deal with source and destinations.</p>
  
  <p>I've experienced strange things installing Sphinx with <code>pip3</code> and playing with the options available to seemingly allow me to install it precisely where I wanted (for some reasons, I want to have each thing in its own directory). I say “playing”, not that I did not read the doc nor tried <code>--help</code>, but because the <code>pip3 help install</code> did not help, and the <a href="http://pip.readthedocs.org/en/latest/reference/pip_install.html">pip install</a> official documentation page is too short on this and actually says not more than the <code>pip3 help install</code>.</p>
  
  <p>Here are the experiments done and the observations.</p>
  
  <h2>First case with <code>--root</code></h2>
  
  <p>I <a href="http://sphinx-doc.org/latest/install.html">downloaded the current Sphinx repository tarball</a>, unpacked it, get into the newly created directory and did:</p>
  
  <pre><code>pip3 install --root /home/&lt;user-name&gt;/apps/sphinx -e .
  </code></pre>
  
  <p>I though this would be the same as <code>--prefix</code>, as there was no <code>--prefix</code> option visibly available. To my surprise, it installed the commands in the <code>bin</code> directory of Python3 (which is also installed locally in its own directory) along to some things in its library directory, and strange, instead of a <code>/home/&lt;user-name&gt;/apps/sphinx</code> directory, I get a <code>/home/&lt;user-name&gt;/apps/sphinx/home/&lt;user-name&gt;/apps/sphinx/…</code>: it appended the specified path to itself.</p>
  
  <p>How especially the last point does make sense? What's the purpose of <code>--root</code>?</p>
  
  <h2>Second case with <code>--target</code></h2>
  
  <p>Then I though if  it's not <code>--root</code>, that may be <code>--target</code>, so I did (after a clean up):</p>
  
  <pre><code>pip3 install --target /home/&lt;user-name&gt;/apps/sphinx -e .  
  </code></pre>
  
  <p>It did not work, complaining about an unrecognized <code>--home</code> option.</p>
  
  <p>What is this <code>--home</code> (which I did not specified) it complains about, and what exactly is <code>--target</code>?</p>
  
  <h2>Third case with <code>--install-option='--prefix=…'</code></h2>
  
  <p>After some web‑searching and a thread on StackOverflow, I tried this:</p>
  
  <pre><code>pip3 install --install-option='--prefix=/home/&lt;user-name&gt;/apps/sphinx' -e .
  </code></pre>
  
  <p>It just complained it could not install a <code>.pth</code> file and something is wrong with my <code>PYTHONPATH</code>, which was addressable restarting the same with the addition of a variable definition:</p>
  
  <pre><code>export PYTHONPATH=/home/&lt;user-name&gt;/apps/sphinx/lib/python3.4/site-packages
  pip3 install --install-option='--prefix=/home/&lt;user-name&gt;/apps/sphinx' -e .
  </code></pre>
  
  <p>I just had to the set <code>PYTHONPATH</code> even before the directory actually exists and anything was installed in it, but this one was OK (whether or not <code>pip</code> should update <code>PYTHONPATH</code> itself during the process and remind to set it up definitively, is a debatable question).</p>
  
  <p>This option, which was the good one, was also the less clearly visible one.</p>
  
  <h2>Another last related one:</h2>
  
  <p>What's the difference between <code>--editable</code> and <code>--src</code>?</p>
  
  <h2>Update #1</h2>
  
  <p>I can't tell if it's Sphinx related, but I noticed two additional things.</p>
  
  <p>Doing </p>
  
  <pre><code>pip3 install --install-option='--prefix=&lt;install-dir&gt;' -e &lt;repository-dir&gt;
  </code></pre>
  
  <p>where <em>repository-dir</em> is a local check out of Sphinx, Sphinx gets installed in <em>install-dir</em>, is listed by <code>pip3 list</code> but can't be uninstalled.</p>
  
  <p>On the opposite, doing</p>
  
  <pre><code>pip3 install --install-option='--prefix=&lt;install-dir&gt;' Sphinx
  </code></pre>
  
  <p>that is, letting <code>pip3</code> retrieving an archive, Sphinx is not installed in <em>install-dir</em>, is installed in the python directory instead, is listed by <code>pip3 list</code> and can be uninstalled.</p>
  
  <p>Depending on whether the source is a local repository or a remote archive, it won't be installed at the same location and will not be or will be uninstallable.</p>
  
  <p>Dependencies were not affected, were handled the same way in both cases (installed where expected, listed, and uninstallable).</p>
  
  <h2>Update #2</h2>
  
  <p>The behaviour with <code>--root</code> make me feel about a kind of fake‑root (like the one you get when building a Debian package or when cross‑compiling). If it's intended to be the same, then the path which surprised me, is on the contrary, expected.</p>