Deprecation: non-bare project name in URL/VCS `egg=` fragments

[ichard26]

Last updated on July 22, 2025.

What's being deprecated

DEPRECATION: file:///home/ichard26/dev/oss/pip/temp/packages/version_pkg#egg=version_pkg<1.16.0 contains an egg 
fragment with a non-PEP 508 name. pip 25.3 will enforce this behaviour change. A possible replacement is to use the req 
@ url syntax, and remove the egg fragment. Discussion can be found at https://github.com/pypa/pip/issues/13157

Hello! If you've received this deprecation warning, you are using an unsupported egg=<pkg> URL fragment. The most likely cause is having a version specifier (e.g., #egg=mypackage>=2.0.0) or an extra specifier (e.g., #egg=mypackage[full]).

What should I do?

The #egg=<pkg> fragment is a legacy feature inherited from setuptools. It was not meant to include anything but a valid project name (as per the formal rules for distributions names).

If there is a version specifier, pip has not and will not honor it, instead choosing to install whatever is served by the URL even if the version is not allowed. Extras were an accepted extension to the #egg=<pkg> fragment syntax (when there wasn't any replacement syntax available), but now there is standard syntax for URL references.

You are strongly encouraged to switch to the Direct URL syntax which allows for the project name to stated in a standard way. Alternatively, you may also simply drop the #egg=<pkg> fragment. It is not required for pip to function in many situations today.

For example, if you have something like:

pip install path/to/mypackage#egg=mypackage[full]

You should change it to use the following syntax:

pip install "mypackage[full] @ path/to/mypackage"

Other examples:

# Legacy, egg fragment form
pip install path/to/mypackage#egg=mypackage
pip install path/to/mypackage#egg=mypackage>1.16.0
pip install https://github.com/pypa/pip/archive/main.zip#egg=pip
pip install git+https://github.com/pypa/pip.git#egg=pip

# Direct URL form
pip install mypackage @ path/to/mypackage
pip install mypackage @ path/to/mypackage
pip install pip @ https://github.com/pypa/pip/archive/main.zip
pip install pip @ git+https://github.com/pypa/pip.git

# Alternatively, simply state the URL, pip will figure out the project name
pip install path/to/mypackage
pip install path/to/mypackage
pip install https://github.com/pypa/pip/archive/main.zip
pip install git+https://github.com/pypa/pip.git

Warning

Editable VCS installs do NOT yet support the Direct URL syntax. This means the egg fragment is the only supported way to request an extra for a VCS URL. If this is your situation, you will need to wait until pip adds Direct URL support for editable VCS installs. We will NOT remove support for URLs with invalid egg fragments until there is a supported alternative for all use-cases.

Thank you. ~Richard

---

Original issue description (for maintainers)

We deprecated anything that isn't a bare project name in an egg fragment in #11567. It's scheduled for removal in pip 25.0. Let's make this an error.

pip/src/pip/_internal/models/link.py

Lines 459 to 475 in 1452429

	def _egg_fragment(self) -> Optional[str]:
	match = self._egg_fragment_re.search(self._url)
	if not match:
	return None
	# An egg fragment looks like a PEP 508 project name, along with
	# an optional extras specifier. Anything else is invalid.
	project_name = match.group(1)
	if not self._project_name_re.match(project_name):
	deprecated(
	reason=f"{self} contains an egg fragment with a non-PEP 508 name",
	replacement="to use the req @ url syntax, and remove the egg fragment",
	gone_in="25.0",
	issue=11617,
	)
	return project_name

cc @woodruffw

[ichard26]

Hmm, editable VCS installs don't support the direct URL syntax. This means the egg fragment is the only supported way to request an extra for VCS URLs. We'd need to revive #9471 before raising an error.

It's probably best to punt this to a later release.

[notatallshaw]

I think uv already supports the syntax "mypackage[extra] @ {VCS_URL}", but I've never looked at how feasible this is in pip or if it's been tried before.

[AndreyOrb]

I use requirements.txt

If I add add optional dependency in egg, it complains about wrong syntax, but allows me to install the requirements.txt
git+https://bitbucket.org/lalala/lalala.git@dev#egg=lalala[excel]

If I add add optional dependency as a prefix, it works just fine. No complains.
lalala[excel]@git+https://bitbucket.org/lalala/lalala.git@dev

pip version: 25.0.1