Updated On : Nov-19,2019 Time Investment : ~15 mins

Overview

pickle module provides serializing and de-serializing functionality for python objects. Serializing also referred to as pickling, marshaling, flattening. Pickling is byte serialization whereas JSON is text serialization.

Serialized data generated by pickle is python-specific. Hence other languages won't be able to de-serialize pickled data by python pickle.

Warning: This module is not secure against malicious unstructured data. Never unpickle data from untrusted sources.

import pickle

Dumping pickled data to file and reading it:

  • pickle.dump(obj,file,protocol=None,fix_imports=True) - It writes serialized/pickled version of obj to file object. Default protocol is 3 and if negative number is given for protocol then it selects HIGHEST_PROTOCOL. If fix_imports is True then it maps new Python 3 module names to Python 2 to avoid failure during read by Python 2.
  • pickle.load(file,fix_imports=True,encoding="ASCII",errors="strict") - It reads data from file object. fix_imports has same use as above method. encoding can be bytes to read 8-bit string as byte objects, latin1 to read numpy array, datetime, date and time instances.

Note: File should be opened in binary mode to write pickled byte stream data to it. File should have write() and read() methods to be used by dump() and load() methods.

with open('pickle_data.dat', 'wb') as f:
    pickle.dump('Writing String data to file', f)
    pickle.dump({'Key':'Value'},f)
    pickle.dump([1,9,4,7,3,5],f)

with open('pickle_data.dat','rb') as f:
    unpickled_string = pickle.load(f)
    unpickled_dict = pickle.load(f)
    unpickled_list = pickle.load(f)
    print(unpickled_string)
    print(unpickled_dict)
    print(unpickled_list)

Writing String data to file
{'Key': 'Value'}
[1, 9, 4, 7, 3, 5]

Generating pickled data as bytes and reading from it:

  • dumps(obj,protocol=None,fix_imports=True) - Same as dump() method but instead of writing pickled data to file, it returns it.
  • loads(bytes_obj,fix_imports=True,encoding='ASCII',errors='strict') - Reads data from bytes object and returns in original format. Other parameters have same meaning as load().
pickled_string = pickle.dumps('Generating pickled text data')
print(type(pickled_string),pickled_string)
pickled_dict = pickle.dumps({'some_key':'some_value'})
print(type(pickled_dict),pickled_dict)
pickled_list = pickle.dumps([4,6,8,9,10])
print(type(pickled_list),pickled_list)

<class 'bytes'> b'\x80\x03X\x1c\x00\x00\x00Generating pickled text dataq\x00.'
<class 'bytes'> b'\x80\x03}q\x00X\x08\x00\x00\x00some_keyq\x01X\n\x00\x00\x00some_valueq\x02s.'
<class 'bytes'> b'\x80\x03]q\x00(K\x04K\x06K\x08K\tK\ne.'

unpickled_text = pickle.loads(pickle.dumps('Generating pickled text data'))
print(unpickled_text, type(unpickled_text))
unpickled_dict = pickle.loads(pickle.dumps({'some_key':'some_value'}))
print(unpickled_dict, type(unpickled_dict))
unpickled_range = pickle.loads(pickle.dumps(range(10)))
print(unpickled_range, type(unpickled_range))
unpickled_list = pickle.loads(pickle.dumps([10,9,8,7,6,5,4,3,2,1]))
print(unpickled_list, type(unpickled_list))

Generating pickled text data <class 'str'>
{'some_key': 'some_value'} <class 'dict'>
range(0, 10) <class 'range'>
[10, 9, 8, 7, 6, 5, 4, 3, 2, 1] <class 'list'>

Pickle Protocol Version available currently:

  • Version 0: It's original human-readable protocol and backward compatible with old python versions.
  • Version 1: Old binary format compatible with previous python versions
  • Version 2: Introduced in Python 2.3. Supports efficient pickling of new-style python classes.
  • Version 3: Introduced in Python 3.0. Default protocol. It cannot be unpickled by Python 2.x. Explicitly support for bytes objects.
  • Version 4: Introduced in Python 3.4. Supports pickling for very large objects, different kinds of objects and different data formats optimizations.

Protocol Constants:

  • pickle.HIGHEST_PROTOCOL - Highest protocol available
  • pickle.DEFAULT_PROTOCOL - Default protocol is version 3 currently.

Pickle module exceptions:

  • pickle.PickleError - Common base class for other Pickling Exceptions. Extends Exception class.
  • pickle.PicklingError - Raised when an unpickable object is encountered by a module. Extends PickleError.
  • pickle.UnpicklingError - Raised when unpickling fails due to corrupt data or security violations. Extends PickleError.
Sunny Solanki  Sunny Solanki

YouTube Subscribe Comfortable Learning through Video Tutorials?

If you are more comfortable learning through video tutorials then we would recommend that you subscribe to our YouTube channel.

Need Help Stuck Somewhere? Need Help with Coding? Have Doubts About the Topic/Code?

When going through coding examples, it's quite common to have doubts and errors.

If you have doubts about some code examples or are stuck somewhere when trying our code, send us an email at coderzcolumn07@gmail.com. We'll help you or point you in the direction where you can find a solution to your problem.

You can even send us a mail if you are trying something new and need guidance regarding coding. We'll try to respond as soon as possible.

Share Views Want to Share Your Views? Have Any Suggestions?

If you want to

  • provide some suggestions on topic
  • share your views
  • include some details in tutorial
  • suggest some new topics on which we should create tutorials/blogs
Please feel free to contact us at coderzcolumn07@gmail.com. We appreciate and value your feedbacks. You can also support us with a small contribution by clicking DONATE.


Tags pickle, marshaling, serialization, flattening
Sunny Solanki

Sunny Solanki

Software Developer | Youtuber | Bonsai Enthusiast

Subscribe to Our YouTube Channel

YouTube SubScribe

Most Popular Python Tutorials

1. ipywidgets - An In-depth Guide to Interactive Widgets in Jupyter Notebook
2. Simple Guide to Style Display of Pandas DataFrames
3. imaplib - Simple Guide to Manage Mailboxes using Python
4. logging.config - Simple Guide to Configure Loggers from Dictionary and Config Files
5. line_profiler: Line by Line Profiling of Python Code

Tutorial Categories

Artificial Intelligence (83)
Data Science (84)
Digital Marketing (8)
Machine Learning (38)
Python (130)

Newsletter Subscription