Registry / devops / pip-requirements-js

pip-requirements-js

library1.0.3jsnpmunverified

pip-requirements-js is a pure JavaScript and TypeScript library designed to robustly parse `requirements.txt`, `constraints.txt`, and `requirements.in` files, strictly adhering to pip's documentation on the requirements file format and PEP 508 for dependency specification. The current stable version is 1.0.3, released on March 9, 2026. The project shows an active development cadence, with several releases in late 2025 and early 2026. Its key differentiator is the use of the Ohm.js parser generator, ensuring high fidelity to Python's pip parsing logic, including complex environment markers and file inclusions. It offers both 'full' and 'loose' parsing modes, with options to include source location information for advanced use cases like editor tooling.

devops serialization testing

npm install pip-requirements-js

github ↗package ↗

INSTALL

IMPORT

SIG · PIP-REQUIREMENTS-J

pip-requirements-js

devopsjavascriptv1.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parsePipRequirementsFile

✓ import { parsePipRequirementsFile } from 'pip-requirements-js';

✗ const parsePipRequirementsFile = require('pip-requirements-js').parsePipRequirementsFile;

Primary function for parsing full file content.

parsePipRequirementsLine

✓ import { parsePipRequirementsLine } from 'pip-requirements-js';

✗ import parsePipRequirementsLine from 'pip-requirements-js/parsePipRequirementsLine';

Used for parsing single lines. Note the named export.

Requirement

✓ import type { Requirement } from 'pip-requirements-js';

Type definition for a parsed requirement. Always import types using 'import type'.

RequirementsSyntaxError

✓ import { RequirementsSyntaxError } from 'pip-requirements-js';

Error class thrown for invalid requirements file syntax.

Demonstrates parsing a multi-line `requirements.txt` string in both standard and location-inclusive modes, including basic error handling for syntax issues.

import { parsePipRequirementsFile, RequirementsSyntaxError } from 'pip-requirements-js'; import type { Requirement, WithLocation } from 'pip-requirements-js'; const requirementsFileContent = ` # My project dependencies Django==4.2.0 ; python_version < '3.12' requests>=2.28.0,<3.0.0 # HTTP library -r base.txt project-core @ file:///local_libs/project_core-1.0-py3-none-any.whl `; try { const requirements: Requirement[] = parsePipRequirementsFile(requirementsFileContent); console.log('Parsed requirements (full):', requirements); const requirementsWithLocations: WithLocation<Requirement>[] = parsePipRequirementsFile( requirementsFileContent, { includeLocations: true } ); console.log('Parsed requirements with locations:', requirementsWithLocations[0].location); } catch (error) { if (error instanceof RequirementsSyntaxError) { console.error('Syntax error in requirements file:', error.message); } else { console.error('An unexpected error occurred:', error); } }

Debug

Known issues

breakingVersion 1.0.0 introduced significant changes, including adding the `includeLocations` parsing option and refining the structure of objects returned by loose parsing functions. Code relying on previous output formats, especially for loose mode or without `includeLocations`, may need adjustments.

fix

Review the API documentation for `parsePipRequirementsFile`, `parsePipRequirementsLine`, and their 'loose' counterparts to adapt to new return types like `WithLocation<T>` and `LooseProjectNameRequirement`.

affects: >=1.0.0

gotchaWhen using `parsePipRequirementsLine`, a `null` value is returned for lines that are syntactically valid but contain no actual requirement (e.g., empty lines or comment-only lines). This is different from `RequirementsSyntaxError` which is thrown for invalid syntax.

fix

Always check for `null` when processing the result of `parsePipRequirementsLine` before attempting to access requirement properties. Handle `RequirementsSyntaxError` separately for parsing failures.

affects: >=0.1.0

gotchaThe `includeLocations` option returns an array of `WithLocation<T>` objects, where the actual parsed data is nested under a `data` property. Ensure you access `item.data` to get the `Requirement` or `LooseProjectNameRequirement`.

fix

When `includeLocations: true` is passed, iterate through the results as `const { data, location } of requirementsWithLocations;` or access `item.data` and `item.location` explicitly.

affects: >=1.0.0

gotchaThe `loose` parsing functions (`parsePipRequirementsFileLoosely`, `parsePipRequirementsLineLoosely`) specifically skip URL-based requirements and references to other requirement/constraints files. They return `LooseProjectNameRequirement` which is a subset of `Requirement`.

fix

If you need to process all types of pip requirements, including URL-based ones or references to other files, use the 'full' parsing functions (`parsePipRequirementsFile`, `parsePipRequirementsLine`).

affects: >=0.2.0

Errors

Common errors & fixes

SyntaxError: Unexpected token 'export'

Attempting to use `require()` with an ESM-only package or an older Node.js version that doesn't fully support ESM.

fix

Ensure you are using Node.js v12+ and using `import` statements in an ESM context (e.g., in a `.mjs` file or with `"type": "module"` in `package.json`).

RequirementsSyntaxError: Expected <some_grammar_rule> but found <unexpected_token> at line <num>, column <num>

The input string passed to a parsing function does not conform to pip's requirements file format or PEP 508.

fix

Review the exact error message, line, and column reported. Correct the syntax in your `requirements.txt` content to match pip's specifications. Common issues include malformed environment markers, incorrect version specifiers, or invalid options.

TypeError: Cannot read properties of null (reading 'data')

Attempting to access properties like `data` or `location` on the result of `parsePipRequirementsLine` when it returned `null` for a comment-only or empty line.

fix

Add a null check before accessing properties of the parsed result: `const result = parsePipRequirementsLine(line); if (result) { /* process result.data or result.location */ }`

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/Twixes/pip-requirements-js ↗

packagehttps://www.npmjs.com/package/pip-requirements-js ↗