jupyter labextension install fails with 'not a valid npm package' error

TL;DR

jupyter labextension install expects a source-style npm package, but since JupyterLab 3 almost every extension ships as a prebuilt pip or conda package, so the installer rejects it as not a valid npm package. Use pip install [extension-name] instead, then rebuild is unnecessary: prebuilt extensions load on next Lab start. Only reach for labextension install when the docs explicitly say the extension has no prebuilt distribution.

jupyter labextension install fails with 'not a valid npm package' error

Use this when

• jupyter labextension install [name] fails with 'not a valid npm package'.
• You are on JupyterLab 3 or 4 and following an old tutorial.
• The extension's docs mention pip install as the install method.

Not for this skill when

• You are developing an extension from source. Then labextension develop is the right tool.
• The extension installs but does not appear. That is a build or version-mismatch issue.

Steps

1. Check your Lab version: jupyter lab --version. Verify: 3.x or 4.x, where prebuilt extensions are the norm.
2. Install via pip: pip install [extension-package-name]. Verify: pip show [extension-package-name] reports it.
3. Confirm Lab sees it: jupyter labextension list. Verify: the extension appears as enabled without a build step.
4. Restart JupyterLab and open the Extension Manager. Verify: the extension loads and its UI appears.
5. If the extension truly has no prebuilt package, clone its repo and use jupyter labextension develop . --overwrite from the source dir. Verify: the develop install links instead of erroring.

Variant phrasings

labextension not a valid npm package

Short form. pip install is the answer.

jupyter lab install extension npm error

General phrasing. Same JupyterLab 3 packaging change.

labextension install fails jupyterlab 4

Version-tagged phrasing. Prebuilt extensions only.

Compatibility: JupyterLab 3.x and 4.x. JupyterLab 2 and earlier still used labextension install with npm packages.

Why it happens

JupyterLab 3 introduced the prebuilt extension system: extensions ship compiled frontend assets inside a normal python package, so pip handles everything and no node build is needed. The old labextension install path expects an npm source package layout, which prebuilt distributions do not have, hence the 'not a valid npm package' rejection. Tutorials written for Lab 2 never got updated.

Edge cases / pitfalls

• The pip package name and the labextension name often differ. Check the extension's README for the exact pip name.
• Installing the extension into the server env when Lab runs from another env does nothing. Match the Lab environment.
• Some extensions need a matching jupyter_server version range. Read the extension's requirements before blaming the install.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7p8ehkjKy30JmbPUAc28eA