pickleparser

library0.5jsnpmunverified

The `pickleparser` library provides a pure JavaScript and TypeScript implementation for parsing Python's pickle serialization format. It supports all pickle protocol versions from 0 to 5, allowing developers to deserialize Python objects directly within Node.js environments and web browsers. Currently stable at version 0.2.1, the project appears to have an active release cadence, frequently adding support for new opcodes and refining its API. A key differentiator is its full protocol support and its utility for converting pickle data to JSON, including a bundled `pickletojson` CLI tool, without relying on Python runtimes. It offers `ParserOptions` for customizing the unpickling process, making it flexible for various use cases.

serialization

npm install pickleparser

github ↗package ↗

INSTALL

IMPORT

SIG · PICKLEPARSER

pickleparser

serializationjavascriptv0.5

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.

Parser

✓ import { Parser } from 'pickleparser';

✗ const { Parser } = require('pickleparser');

The `Parser` class is the primary interface for unpickling. While CommonJS (CJS) syntax might work in some setups, ESM is the recommended and best-supported import style for modern Node.js and bundlers.

ParserOptions

✓ import type { ParserOptions } from 'pickleparser';

✗ import { ParserOptions } from 'pickleparser';

Used for configuring parser behavior (e.g., custom object handling). As `ParserOptions` is typically an interface or type, prefer `import type` to ensure it's treated as a type-only import, which avoids potential runtime issues or bundle size increases.

pickleparser (global)

✓ const parser = new pickleparser.Parser();

✗ import { pickleparser } from 'pickleparser';

In browser environments where the library is loaded via a `<script>` tag, `pickleparser` becomes a global object. Do not attempt to use this global access pattern in Node.js or when using module bundlers, where explicit imports are required.

Demonstrates how to read a Python pickle file from disk using Node.js, parse it with `pickleparser`, and log the resulting JavaScript object to the console, including a `BigInt` replacer for `JSON.stringify()`.

import fs from 'node:fs/promises'; import path from 'node:path'; import { Parser } from 'pickleparser'; async function unpickleFile(filePath: string) { try { // Read the pickle file as raw binary data (Buffer in Node.js) const pklData = await fs.readFile(filePath, null); const buffer = Buffer.from(pklData); // Initialize the parser and parse the buffer const parser = new Parser(); const obj = parser.parse(buffer); // Log the parsed object. Use a replacer for JSON.stringify to handle BigInts. console.log(JSON.stringify(obj, (key, value) => typeof value === 'bigint' ? value.toString() + 'n' : value , 2)); } catch (error) { console.error(`Error unpickling file ${filePath}:`, error); } } // Example usage: Ensure a pickle file exists at the specified path. // For demonstration, we use an environment variable or a default. unpickleFile(process.env.PICKLE_FILE_PATH ?? './example.pkl'); // To create a dummy pickle file for testing (run this in Python): // import pickle // data = {'message': 'Hello from Python!', 'value': 12345678901234567890, 'items': [1, 2, 3]} // with open('example.pkl', 'wb') as f: // pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)

pickletojson --version

Debug

Known issues

breakingThe public API underwent a significant refactor for improved extensibility in version `0.1.0-beta.0`. Users upgrading from pre-`0.1.0-beta.0` versions must adjust their import statements and parsing logic.

fix

Refer to the latest documentation and examples for `Parser` class instantiation and method calls. The module now primarily uses named exports like `Parser`.

affects: <0.1.0-beta.0

gotchaPython pickle files can contain large integers that, when parsed, are represented as JavaScript `BigInt` primitives. Standard `JSON.stringify()` cannot directly serialize `BigInt` values and will throw a `TypeError` if not handled.

fix

Provide a custom `replacer` function to `JSON.stringify()` to convert `BigInt`s to strings or another serializable format. For example: `JSON.stringify(obj, (key, value) => typeof value === 'bigint' ? value.toString() + 'n' : value)`.

affects: >=0.0.1

breakingEarlier versions (prior to `0.0.2-alpha.2`) contained an issue with insecure string handling in pickle protocol 0. This security vulnerability was addressed in `0.0.2-alpha.2`.

fix

Upgrade to `pickleparser@0.0.2-alpha.2` or newer immediately to ensure all known security fixes are applied and to benefit from the most stable and secure parsing logic.

affects: <0.0.2-alpha.2

gotchaParsing untrusted Python pickle data is a significant security risk. In Python, unpickling arbitrary data can lead to arbitrary code execution due to the nature of the pickle protocol. While `pickleparser` is a JavaScript implementation and does not execute Python code, the reconstructed JavaScript objects could still contain malicious data structures (e.g., specific string values, function names) that, if processed without sanitization in the consuming JavaScript application, could lead to security vulnerabilities.

fix

**Never parse pickle files from untrusted or unverified sources.** Always treat parsed data as potentially hostile and implement robust validation and sanitization before using it within your application logic.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: Do not know how to serialize a BigInt

Attempting to `JSON.stringify()` an object parsed from a pickle file that contains `BigInt` values without a custom `replacer` function.

fix

Modify your `JSON.stringify()` call to include a `replacer` function that converts `BigInt` values to strings or another serializable type: `JSON.stringify(obj, (key, value) => typeof value === 'bigint' ? value.toString() : value)`.

Error: Input must be a Buffer or Uint8Array

The `parser.parse()` method was invoked with an incorrect data type (e.g., a plain string or an object) instead of a `Buffer` (Node.js) or `Uint8Array` (browser) containing the raw binary pickle data.

fix

Ensure the input data is read in binary format and converted to the correct type. For Node.js, use `fs.readFileSync(filePath, null)` to get a `Buffer`. For browsers, use a `FileReader` to read as `ArrayBuffer` and convert to `Uint8Array`.

ReferenceError: pickleparser is not defined

This error typically occurs when trying to use `new pickleparser.Parser()` in a browser environment where the `pickleparser` global script was not correctly loaded, or in a Node.js environment where this global access pattern is invalid.

fix

In browser applications, verify the library's `<script>` tag is correctly placed and loaded. In Node.js or module-based environments, use explicit ESM `import { Parser } from 'pickleparser';` or CJS `const { Parser } = require('pickleparser');`.

Upgrade

Version history

0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/ewfian/pickleparser ↗

packagehttps://www.npmjs.com/package/pickleparser ↗