--extra-search-dir only supports alternative versions for pip.

[qwcode]

the -extra-search-dir feature as described in the docs to support alternative versions, only works for pip (and even it's support for pip is pretty limited; see below)

I don't see that it could have ever worked as described.

for distribute and setuptools, alternative archives can be found in an alternative directory, but only if they are the default version, which defeats the point of the feature.

for pip, alternative versions of pip can be found, but only if there is no greater version of pip, in the search dir path.

Details for distribute:
supposing you have an alternative source dist of distribute in an extra dir (i.e. not the DEFAULT_VERSION specified in the embedded distribute_setup.py), virtualenv will find that version, but distribute_setup.py (as a called script) is only capable of installing the DEFAULT_VERSION. See the download_setuptools method in distribute_setup.py and follow the code leading up to it. Btw, any cli arguments passed to distribute_setup.py are used as install arguments to the python setup.py install call for distribute.

Details for setuptools:
Supposing you have an alternative version of setuptools in an extra dir (i.e. not the DEFAULT_VERSION specified in the embedded ez_setup.py), virtualenv will find the egg, and pass it as an argument to ez_setup.py (and add it to the PYTHONPATH). Due to the internals of ez_setup.py, what happens is the found version gets installed, then uninstalled, and then the DEFAULT_VERSION get's installed.

[carljm]

If you've verified this in practice, I think it makes sense to fix the docs to match the actual behavior first.

[dholth]

Also it seems to prefer its own bundled pip against a pip with the same or lesser version in extra-search-dirs...

[qwcode]

@ejucovy , maybe you can respond to this. I think you documented this as working 2 years ago.

[Ivoz]

What follows is me creating virtualenvs, firstly with setuptools 1.1.6 in /home/ivo/dists/, then 1.1.3, then without the option --extra-search-dir. In each case, the virtualenv created seemed to have the setuptools that I would have expected.

I found this issue because it's warned that --extra-search-dir doesn't work at all in the docs @

http://www.virtualenv.org/en/latest/#the-extra-search-dir-option

Has it been fixed without updating the documentation / this issue?

ivo@ivosung ~$ mkvirtualenv --extra-search-dir=/home/ivo/dists/ sttest
Running virtualenv with interpreter /usr/bin/python2
New python executable in sttest/bin/python2
Also creating executable in sttest/bin/python
Installing Setuptools.......................................................................................................................................................................................................................................done.
Installing Pip.....................................................................................................................................................................................................................................................................................................................................done.
(sttest)ivo@ivosung ~$ pip list
pip (1.4.1)
setuptools (1.1.6)
wsgiref (0.1.2)
(sttest)ivo@ivosung ~$ deactivate 
ivo@ivosung ~$ rmvirtualenv sttest
Removing sttest...
ivo@ivosung ~$ mkvirtualenv --extra-search-dir=/home/ivo/dists/ sttest
Running virtualenv with interpreter /usr/bin/python2
New python executable in sttest/bin/python2
Also creating executable in sttest/bin/python
Installing Setuptools....................................................................................................................................................................................................................................done.
Installing Pip.....................................................................................................................................................................................................................................................................................................................................done.
(sttest)ivo@ivosung ~$ pip list
pip (1.4.1)
setuptools (1.1.3)
wsgiref (0.1.2)
(sttest)ivo@ivosung ~$ ls /home/ivo/dists
setuptools-1.1.3.tar.gz
(sttest)ivo@ivosung ~$ deactivate 
ivo@ivosung ~$ rmvirtualenv sttest
Removing sttest...
ivo@ivosung ~$ mkvirtualenv sttest
Running virtualenv with interpreter /usr/bin/python2
New python executable in sttest/bin/python2
Also creating executable in sttest/bin/python
Installing Setuptools..............................................................................................................................................................................................................................done.
Installing Pip.....................................................................................................................................................................................................................................................................................................................................done.
(sttest)ivo@ivosung ~$ pip list
pip (1.4.1)
setuptools (0.9.8)
wsgiref (0.1.2)

[qwcode]

@Ivoz interesting. maybe it has been fixed indirectly. let me look and confirm later.

[qwcode]

yes, it's working again. PR #432 from @pfmoore 5 months ago indirectly fixed this.
I'll update the docs.