A pure TypeScript parser for the Python pickle format. Supports protocol 0 through 5.
- Pickle protocol version 0~5, all opcodes supported
- Pure TypeScript, zero dependencies
- Works in Node.js and browsers
- Customizable via
ParserOptions(name resolution, dict/set types, out-of-band buffers) - CLI tool to convert pickle files to JSON
Online Pickle to JSON Converter
npm install pickleparserimportfsfrom'node:fs/promises';import{Parser}from'pickleparser';constbuffer=awaitfs.readFile('data.pkl');constobj=newParser().parse(buffer);console.log(obj);<scriptsrc="https://unpkg.com/pickleparser/dist/index.js"></script><script>constbuffer=newUint8Array(arrayBuffer);constobj=newpickleparser.Parser().parse(buffer);</script>npx pickleparser file.pkl file.json
# or
npm i pickleparser -g
pickletojson file.pkl file.jsonimport{Parser}from'pickleparser';constparser=newParser({unpicklingTypeOfDictionary: 'Map',unpicklingTypeOfSet: 'Set',});constresult=parser.parse<MyType>(buffer);| Option | Type | Default | Description |
|---|---|---|---|
unpicklingTypeOfDictionary | 'object' | 'Map' | 'object' | Python dict maps to JS plain object or Map |
unpicklingTypeOfSet | 'array' | 'Set' | 'array' | Python set maps to JS array or Set |
nameResolver | NameResolver | built-in | Resolve Python classes/functions by module and name |
persistentResolver | PersistentResolver | throws | Resolve persistent object references |
extensionResolver | ExtensionResolver | throws | Resolve extension registry codes |
buffers | Iterator<any> | undefined | Out-of-band buffers for protocol 5 |
Register custom constructors to control how Python classes are instantiated:
import{Parser,NameRegistry}from'pickleparser';classMyClass{x: number=0;y: number=0;}constregistry=newNameRegistry().register('mymodule','MyClass',MyClass);constobj=newParser({nameResolver: registry}).parse<MyClass>(buffer);| Python | JavaScript | Notes |
|---|---|---|
dict | {} or Map | controlled by unpicklingTypeOfDictionary |
list | Array | |
tuple | Array | |
set, frozenset | Array or Set | controlled by unpicklingTypeOfSet |
str | string | |
bytes, bytearray | Buffer (Node.js) | |
int | number | |
int (> 2^53) | number with precision loss, or BigInt via LONG4 | |
float | number | including inf, -inf, nan |
bool | boolean | |
None | null |
| Protocol | Python Version | PEP |
|---|---|---|
| 0 | all | |
| 1 | all | |
| 2 | 2.3+ | PEP 307 |
| 3 | 3.0+ | |
| 4 | 3.4+ | PEP 3154 |
| 5 | 3.8+ | PEP 574 |
For opcode-level details, see Supported Opcodes.
MIT