{"id":16877,"library":"pickleparser","title":"Python Pickle Parser for JavaScript","description":"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.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/ewfian/pickleparser","tags":["javascript","pickle","parser","python","unpickling","pure-javascript","typescript","json"],"install":[{"cmd":"npm install pickleparser","lang":"bash","label":"npm"},{"cmd":"yarn add pickleparser","lang":"bash","label":"yarn"},{"cmd":"pnpm add pickleparser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { Parser } = require('pickleparser');","symbol":"Parser","correct":"import { Parser } from 'pickleparser';"},{"note":"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.","wrong":"import { ParserOptions } from 'pickleparser';","symbol":"ParserOptions","correct":"import type { ParserOptions } from 'pickleparser';"},{"note":"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.","wrong":"import { pickleparser } from 'pickleparser';","symbol":"pickleparser (global)","correct":"const parser = new pickleparser.Parser();"}],"quickstart":{"code":"import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport { Parser } from 'pickleparser';\n\nasync function unpickleFile(filePath: string) {\n    try {\n        // Read the pickle file as raw binary data (Buffer in Node.js)\n        const pklData = await fs.readFile(filePath, null); \n        const buffer = Buffer.from(pklData);\n\n        // Initialize the parser and parse the buffer\n        const parser = new Parser();\n        const obj = parser.parse(buffer);\n        \n        // Log the parsed object. Use a replacer for JSON.stringify to handle BigInts.\n        console.log(JSON.stringify(obj, (key, value) =>\n            typeof value === 'bigint' ? value.toString() + 'n' : value\n        , 2));\n    } catch (error) {\n        console.error(`Error unpickling file ${filePath}:`, error);\n    }\n}\n\n// Example usage: Ensure a pickle file exists at the specified path.\n// For demonstration, we use an environment variable or a default.\nunpickleFile(process.env.PICKLE_FILE_PATH ?? './example.pkl');\n\n// To create a dummy pickle file for testing (run this in Python):\n// import pickle\n// data = {'message': 'Hello from Python!', 'value': 12345678901234567890, 'items': [1, 2, 3]}\n// with open('example.pkl', 'wb') as f:\n//     pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)\n","lang":"typescript","description":"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()`."},"warnings":[{"fix":"Refer to the latest documentation and examples for `Parser` class instantiation and method calls. The module now primarily uses named exports like `Parser`.","message":"The 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.","severity":"breaking","affected_versions":"<0.1.0-beta.0"},{"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)`.","message":"Python 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"Earlier 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`.","severity":"breaking","affected_versions":"<0.0.2-alpha.2"},{"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.","message":"Parsing 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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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)`.","cause":"Attempting to `JSON.stringify()` an object parsed from a pickle file that contains `BigInt` values without a custom `replacer` function.","error":"TypeError: Do not know how to serialize a BigInt"},{"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`.","cause":"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.","error":"Error: Input must be a Buffer or Uint8Array"},{"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');`.","cause":"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.","error":"ReferenceError: pickleparser is not defined"}],"ecosystem":"npm","meta_description":null}