134

When I do a "pip install -e ..." to install from a git repo, I have to specify #egg=somename or pip complains. For example:

pip install -e git://github.com/hiidef/oauth2app.git#egg=oauth2app

What's the significance of this "egg" string?

Lorin Hochstein
  • 57,372
  • 31
  • 105
  • 141
  • 1
    [This part of the `pip install` documentation](https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support) talks about `#egg=name`, but doesn't give a clear answer. – Christian Long Jul 06 '18 at 16:00

5 Answers5

50

per pip install -h the "egg" string is the directory that gets checked out as part of the install

Will Ayd
  • 6,767
  • 2
  • 36
  • 39
  • 15
    Can this just be the same name as the repository? Does cases matter? – CMCDragonkai Oct 29 '13 at 17:50
  • 20
    "The directory that gets checked out"? So do I enter the branch name? Make something up? – Chris Jun 07 '16 at 21:38
  • 2
    If you've made a custom Python package, when you ran setuptools, a directory named `project-name.egg-info/top_level.txt` should have been created. Use the contents of this file as the value for the `egg` parameter. – Daniel May 18 '17 at 00:09
  • 2
    I can't seem to figure out if the `egg=...` setting actually matters. The package I'm installing has multiple entries in the top_level.txt file. I've experimented with matching it to the `name` kwarg the script uses in `setup.py` but also an arbitrary value. The results seem to be the same either way. Note that I'm installing using the `pip install https://...` syntax which doesn't require `-e`. – Taylor D. Edmiston Aug 08 '17 at 01:43
32

An Egg is just some bundled python code. In a git url, the egg is the project name. VCS Support

Normally we install python packages from Pypi, so you specify ONLY the package name and version (or it assumes latest version if you don't specify). Pypi then searches for which egg you want and pip installs that. pip install celery would install the latest published egg and pip install celery[redis] would install a different egg that contains the same celery package and also installs the the latest eggs from whatever packages were listed as dependencies for redis in celery's setup.py.

With git and gitlab paths, you specify /{user|group}/{repository}.git@{tag}#egg={package-name}. there is a difference between #egg=celery and #egg=celery[redis], but they will both come from the same source code.

"tag" can also be a branch or commit hash in addition to an actual tag. It is assumed to be master if you do not specify.

for example, git+https://github.com/celery/celery.git#egg=celery==4.3.0 would check out the master branch and install that. Even though you specified a version number, it is not taken into account in the installation. THE VERSION NUMBER IS IGNORED

When installing via git or other VCS urls, you will want to find the tag or hash of the version you need. For example, git+https://github.com/celery/celery.git@v4.3.0#egg=celery which will checkout the commit tagged "v4.3.0" and then install the package from that source code. Assuming the maintainers did not egregiously mis-tag their repositories, you can get the version you want like that.

jmunsch
  • 22,771
  • 11
  • 93
  • 114
krethika
  • 3,908
  • 1
  • 24
  • 27
13

https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support says:

The "project name" component of the url suffix "egg=-" is used by pip in its dependency logic to identify the project prior to pip downloading and analyzing the metadata. The optional "version" component of the egg name is not functionally important. It merely provides a human-readable clue as to what version is in use. For projects where setup.py is not in the root of project, "subdirectory" component is used. Value of "subdirectory" component should be a path starting from root of the project to where setup.py is located.

From this I deduce that the egg value is only used for dependency checks and therefore I think, by convention, the package name (i.e. some-pypi-package-name) should be used, not any contained folder (i.e. some_pypi_package_name)

Mario
  • 2,619
  • 1
  • 24
  • 22
8

You have to include #egg=Package so pip knows what to expect at that URL. See https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support

more on eggs

Nick T
  • 25,754
  • 12
  • 83
  • 121
Skylar Saveland
  • 11,116
  • 9
  • 75
  • 91
  • 30
    What does that mean "so pip knows what to expect at that url?" Is there something other than #egg that's valid to append to an url like that? – Lorin Hochstein Aug 06 '12 at 20:41
  • I actually like Will's answer from the `pip install -h`, `Source will be checked out into src/PACKAGE (lower-case) and installed in-place (using setup.py develop)` I'm not sure that it is used elsewhere ... – Skylar Saveland Aug 06 '12 at 20:50
  • It's cloned but not installed :( – holms Mar 04 '16 at 03:44
1

Quoting the manual:

pip looks at 2 fragments for VCS URLs:

egg: For specifying the “project name” for use in pip’s dependency resolution logic. eg: egg=project_name

subdirectory: For specifying the path to the Python package, when it is not in the root of the VCS directory. eg: pkg_dir

Adam Matan
  • 128,757
  • 147
  • 397
  • 562