pip-json 0.1.1

Manage Python dependencies via a requirements.json file — npm-style, powered by pip.

pip-json

A lightweight dependency management layer on top of pip, inspired by npm's package.json.

pip-json introduces requirements.json as the project-level dependency manifest. It does not replace pip — it delegates all installs to pip while keeping your dependency intent and resolved state in JSON.

---

Installation

pip install pip-json

For development:

pip install -e ".[testing]"

---

Usage

Install packages

pip-json install requests
pip-json install "requests>=2.0" flask

Installs via pip and writes the constraint to requirements.json. The resolved exact version is written to requirements.lock.json.

Install from a project

pip-json install           # uses requirements.json in or above cwd
pip-json install .         # uses requirements.json in current directory
pip-json install ../other  # uses requirements.json in another directory

Freeze the current environment

pip-json freeze

Captures all installed packages with exact versions into requirements.lock.json. Does not touch requirements.json.

Sync the environment to your manifest

pip-json sync

Installs all packages listed in requirements.json (using their constraints) and updates requirements.lock.json with resolved versions.

---

File Format

requirements.json — your project's dependency intent:

{
  "dependencies": {
    "requests": ">=2.0",
    "flask": "*"
  }
}

requirements.lock.json — exact resolved versions, always co-located with requirements.json:

{
  "dependencies": {
    "requests": "2.32.5",
    "flask": "3.1.0"
  }
}

Commit both files. requirements.json expresses what you want; requirements.lock.json records what pip resolved.

---

File Discovery

pip-json treats dependency files as project-scoped, not environment-scoped.

Starting from the current directory, it walks up the directory tree until requirements.json is found. If none is found, it creates one in the current directory. This means:

• You can run pip-json from any subdirectory of your project.
• Monorepos with nested projects work as expected.

---

Design

Concern	Responsibility
Installing packages	pip (environment-level)
Recording dependency intent	requirements.json (project-level)
Recording resolved versions	requirements.lock.json (project-level)

pip-json sits between your project and pip — a thin, predictable layer with no magic.

Why JSON?

• Structured and machine-readable
• Easy to extend (dev deps, metadata, etc.)
• Familiar to developers coming from npm / yarn

Why not modify pip?

pip has no plugin system and its internal APIs are unstable. A subprocess wrapper is more stable and simpler to reason about.

---

Contributing

See CONTRIBUTING.md.

---

Changelog

See CHANGELOG.md.

---

License

MIT — see LICENSE.