https://github.com/ewfian/pickleparser
A pure Javascript implemented parser for Python pickle format
https://github.com/ewfian/pickleparser
browser json nodejs parser pickle pure-javascript python typescript unpickling without-dependencies
Last synced: 3 months ago
JSON representation
A pure Javascript implemented parser for Python pickle format
- Host: GitHub
- URL: https://github.com/ewfian/pickleparser
- Owner: ewfian
- License: mit
- Created: 2023-04-08T16:46:42.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-06-30T14:46:52.000Z (7 months ago)
- Last Synced: 2025-10-01T09:53:06.254Z (4 months ago)
- Topics: browser, json, nodejs, parser, pickle, pure-javascript, python, typescript, unpickling, without-dependencies
- Language: TypeScript
- Homepage: https://ewfian.github.io/pickleparser/
- Size: 943 KB
- Stars: 19
- Watchers: 2
- Forks: 4
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Support: SUPPORTED_OPCODES.md
Awesome Lists containing this project
README
# Pickle Parser
[](https://www.npmjs.com/package/pickleparser)
[](https://github.com/ewfian/pickleparser/actions/workflows/unit_test.yml)
[](https://ewfian.github.io/pickleparser/)
[](https://github.com/ewfian/pickleparser)
A pure Javascript implemented parser for [Python pickle format](https://docs.python.org/3.11/library/pickle.html)
## Features
* Fully supports Pickle protocol version 0~5 opcodes.
* Pure Typescript implemented.
* Provides `ParserOptions` to customize Unpickling.
* Supports Browser.
* Supports Node.js.
* Provides tool to convert pickle file to JSON.
## Supported Protocol Version
* Pickle protocol version 0
* Pickle protocol version 1
* [Pickle protocol version 2 (Python 2.3)](https://peps.python.org/pep-0307/)
* Pickle protocol version 3 (Python 3.0)
* [Pickle protocol version 4 (Python 3.4)](https://peps.python.org/pep-3154/)
* [Pickle protocol version 5 (Python 3.8)](https://peps.python.org/pep-0574/)
For more details, see: [Supported Opcodes](./SUPPORTED_OPCODES.md)
## Demo
[Online Pickle to JSON Convertor](https://ewfian.github.io/pickleparser/)
## Installation
```sh
$ npm install pickleparser
```
## Usage
### Node.js
```typescript
import fs from 'node:fs/promises';
import path from 'node:path';
import { Parser } from 'pickleparser';
async function unpickle(fname: string) {
const pkl = await fs.readFile(path.join(fname), 'binary');
const buffer = Buffer.from(pkl, 'binary');
const parser = new Parser();
return parser.parse(buffer);
}
const obj = await unpickle('pickled.pkl');
console.log(obj);
```
### Browser
```javascript
const fileSelector = document.getElementById('file_selector');
const jsonResultPreviewer = document.getElementById('json_result_previewer');
fileSelector.addEventListener('change', function (e) {
const file = fileSelector.files[0];
const reader = new FileReader();
reader.onload = function (event) {
const buffer = new Uint8Array(event.target.result);
const parser = new pickleparser.Parser();
const obj = parser.parse(buffer);
const json = JSON.stringify(obj, null, 4);
jsonResultPreviewer.innerText = json;
}
reader.readAsArrayBuffer(file);
});
```
### Terminal
```bash
npx pickleparser file.pkl file.json
# or
npm i pickleparser -g
pickletojson file.pkl file.json
```
## License
MIT