lpip

Git-backed, name-oriented front end to pip for internal Python packages — no internal PyPI registry required.

Install from PyPI as esys-lpip (pip install esys-lpip); the command and import remain lpip.

Status

What this is

lpip (local-pip) resolves a logical package name from a TOML catalog (lpip-sources.toml), validates configuration and prerequisites, and delegates installation to python -m pip install .... The catalog may be a local file or a Git-backed checkout in a persistent user cache.

It is a small client, not a package manager replacement, registry, or service (ADR-0001, ADR-0004).

Why Git instead of a private index

A private package index is a second service: you host it, keep it up, and invent another login. lpip treats Git as the index. Names resolve to git+ URLs; pip installs the tree. Access control is whatever you already use to clone — typically SSH keys or deploy keys. No extra account, no extra host, no extra secret type.

Public PyPI is how you install this tool. Internal packages stay in the Git you already operate.

Non-goals (v1)

• Internal package index or hosted registry
• A dependency resolver other than pip
• Background daemons, lockfile solving, or workspace orchestration

Quick start

pip install esys-lpip
lpip --help

From a clone (contributors):

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix: source .venv/bin/activate
pip install -e ".[dev]"
pytest

Re-run scripts/setup-dev after clone if you need pre-commit and gitlint hooks (see docs/workflow/adoption.md).

Intended configuration

Local catalog:

[source]
type = "file"
path = "~/company/lpip-sources.toml"

Git-backed catalog:

[source]
type = "git"
url = "ssh://git.company/dev/lpip-catalog.git"
revision = "main"
path = "lpip-sources.toml"
refresh = "auto"

Example catalog entry:

[packages.libfoo]
url = "git+ssh://git.company/libs/libfoo.git"
revision = "main"
subdirectory = "python"

Author that file in the catalog Git repository (then commit and push). --url is a normal clone URL (ssh://, https://, or git@host:path); lpip stores git+ssh / git+https for pip:

cd /path/to/lpip-catalog
lpip catalog init
lpip catalog add libfoo --url ssh://git.company/libs/libfoo.git --revision main --subdirectory python
# or: lpip catalog add   # prompts for missing fields

Consumers only fetch (source.type = git + lpip catalog refresh). add / init do not write the consumer cache.

Register more than one catalog (first name wins on install):

lpip source add company --type git --url ssh://git@gitlab.com/org/lpip-catalog.git --revision main
lpip source add local --type file --path ~/lpip-sources.toml
lpip source list
lpip source remove local

Install a mixed list (lpip-requirements.txt is the usual name): catalog names first, then pip for the rest. Bare lpip install NAME still fails if the name is not in the catalog.

lpip install libfoo==1.2.3
lpip install -r lpip-requirements.txt
lpip install -r lpip-requirements.txt --catalog-only

== on a catalog name selects the Git tag (1.2.3 or v1.2.3). Other specifiers on catalog names fail; PyPI lines in -r are passed to pip as-is.

List Git tags that parse as versions (optional leading v): lpip versions libfoo or lpip index versions libfoo (--pre, --all).

lpip version / lpip --version print this tool’s installed version.

lpip install --upgrade / -U and lpip upgrade pass pip --upgrade (same for -r).

Commands: lpip install, lpip upgrade, lpip list, lpip show, lpip versions, lpip version, lpip validate (--strict fails on name clashes across sources), lpip doctor, lpip catalog … (init, add, refresh, …), lpip source … (list, add, remove), lpip config …, lpip index versions. Details: docs/architecture/cli-and-configuration.md.

Documentation

License

MIT (pyproject.toml).