Registry / database / django-picklefield

django-picklefield

JSON →
library3.4.0pypypi✓ verified 25d ago

django-picklefield provides an implementation of a pickled object field for Django models. It enables storing any picklable Python object directly in a database field, handling automatic serialization and deserialization. The library is currently at version 3.4.0 and maintains a healthy release cadence, with updates typically occurring at least once a year to support newer Django and Python versions.

pip install django-picklefield
INSTALL
IMPORT
SIG · DJANGO-PICKLEFIELD
D
django-picklefield
databasepythonv3.4.0
Install
3.5s avg
Import
633ms
Disk
66MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.4.0 · pip install
no network on importno background threads
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
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.674s · 66.3MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.5s · import 0.592s · 67MB
66MB installed
● package 66MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PickledObjectField
from picklefield.fields import PickledObjectField

Define a model with `PickledObjectField` to store any picklable Python object. The `compress=True` argument can be used to enable zlib compression for larger objects. Data is automatically serialized upon saving and deserialized upon retrieval. The provided code demonstrates model definition and illustrates how to use the field to store complex data, including custom class instances.

import os from django.db import models from picklefield.fields import PickledObjectField # Configure Django for a minimal setup (usually done in settings.py) os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings') # This is a dummy settings file for demonstration. In a real project, # ensure 'picklefield' is in INSTALLED_APPS. # A real settings.py would look something like: # INSTALLED_APPS = ['django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'picklefield', 'myapp'] # DATABASES = {'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}} # SECRET_KEY = 'insecure-dev-key' class MyModel(models.Model): data = PickledObjectField(compress=True) def __str__(self): return f"MyModel with data: {self.data}" # Example Usage (assuming Django setup is complete, e.g., via manage.py shell) if __name__ == '__main__': # This part would typically be run within a Django shell or application context # For a standalone runnable example, mocking Django ORM is complex. # The following illustrates usage, but won't run directly without a full Django setup. # Create a dummy class to demonstrate pickling custom objects class CustomObject: def __init__(self, name, value): self.name = name self.value = value def __repr__(self): return f"CustomObject(name='{self.name}', value={self.value})" print("To run this, ensure Django is configured and 'picklefield' is in INSTALLED_APPS.") print("Then run `python manage.py shell` and execute the following:") print(" from myapp.models import MyModel") print(" from myapp.quickstart import CustomObject") # assuming this code is in myapp/quickstart.py print(" obj = MyModel() obj.data = {'list': [1, 2, {'a': 3}], 'custom': CustomObject('test', 123)} obj.save() retrieved_obj = MyModel.objects.first() print(f'Stored data: {retrieved_obj.data}') print(f'Type of retrieved data: {type(retrieved_obj.data)}') print(f'Type of custom object: {type(retrieved_obj.data["custom"])}')")
Debug
Known issues
breakingStoring untrusted or user-controlled data directly in `PickledObjectField` can lead to arbitrary code execution (insecure deserialization). The Python `pickle` module is inherently unsafe when handling data from untrusted sources. `django-picklefield` explicitly marks the field as `editable=False` to prevent declarative usage in Django forms and the admin, but direct assignment of unsanitized user input remains a critical risk.
fix
NEVER store user-controllable data directly in a `PickledObjectField`. For user-provided data, use secure serialization formats like JSON, or ensure strict validation and sanitization. If `picklefield` is used for internal, trusted data, ensure no untrusted input can influence the stored objects.
affects: All versions
gotchaQuerying a `PickledObjectField` using `QuerySet.values()` or `QuerySet.values_list()` will return the raw, base64-encoded pickled string, not the deserialized Python object. You will need to manually decode and unpickle these values if you want the original Python objects.
fix
After retrieving data with `values()` or `values_list()`, manually decode and unpickle the string. For example, using the internal `dbsafe_decode` function if accessed, or simply `pickle.loads(base64.b64decode(value))` if `compress=False` was used.
affects: All versions
gotchaDirectly storing instances of other Django models in a `PickledObjectField` can lead to issues due to how Django models manage their state and references, especially after model definition changes or during migrations.
fix
If you need to store Django model instances, wrap them in a simple data structure like a list or tuple (e.g., `obj.data = [my_django_model_instance]`) before assigning them to the `PickledObjectField`.
affects: All versions
breakingMajor versions of `django-picklefield` have specific compatibility requirements for Python and Django versions. For instance, version 3.4.0 supports Django 6.0 and Python 3.10+ (including Python 3.14), but dropped support for Python 3.9. Version 3.3.0 dropped support for Django 3.2, 4.0, and 4.1.
fix
Always check the `django-picklefield` release notes or `pyproject.toml` for explicit Python and Django version compatibility before upgrading. Ensure your project's Python and Django versions meet the requirements of the `django-picklefield` version you intend to use.
affects: Prior to 3.4.0, or when upgrading across major versions.
gotchaIf the class definition of an object stored in a `PickledObjectField` changes significantly after it has been pickled (e.g., attributes are removed, renamed, or types change), attempting to unpickle older data might result in `AttributeError`, `TypeError`, or other deserialization errors.
fix
Plan for backward compatibility when modifying classes stored in `PickledObjectField`. Consider versioning your pickled objects, implementing custom `__setstate__` and `__getstate__` methods, or providing migration logic for old object structures if breaking changes are necessary.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'picklefield.fields'
The `django-picklefield` library is either not installed, or the import path in your Django model is incorrect.
fix
Ensure `django-picklefield` is installed (`pip install django-picklefield`) and your model imports `PickledObjectField` from `picklefield.fields`: `from picklefield.fields import PickledObjectField`.
TypeError: can't pickle <object type>
The Python `pickle` module has limitations and cannot serialize certain types of objects, such as `_thread.lock` objects, local functions, or complex Django QuerySet objects containing unpicklable internal states.
fix
Modify the object being stored to exclude unpicklable components, ensure all parts are defined at the top level of a module, or convert complex objects like QuerySets into simpler, picklable data structures (e.g., lists of IDs or dictionaries) before saving. For Django models, store their primary keys rather than the model instances directly if possible.
TypeError: ('unpickling failed for field %s', ('field_name',)) or objects stored as strings after refactoring
When a Python class that was previously pickled and stored in a `PickledObjectField` is moved, renamed, or its module structure changes, the `pickle` module may fail to locate and deserialize the original class, often resulting in `TypeError` during unpickling or the raw encoded string being returned instead of the Python object.
fix
Avoid moving or renaming classes whose instances are stored in `PickledObjectField`. If unavoidable, create a 'ghost' class at the old location that imports and re-exposes the moved class, or implement custom serialization logic to handle class migrations. For Python 2 to 3 migrations, ensure data is migrated correctly as pickle protocols can differ.
TypeError: Lookup type %s is not supported.
The `PickledObjectField` explicitly limits the types of database lookups it supports to 'exact', 'in', and 'isnull' to ensure reliable querying of pickled data.
fix
Refactor your queries to use only the supported lookup types: `exact`, `in`, or `isnull`. If more complex queries are needed, consider storing queryable attributes in separate, standard Django fields, or perform deserialization and filtering in Python code after retrieving objects.
Upgrade
Version history
3.4.0latest on PyPI · released Nov 27, 2025
Audit
Dependencies
DjangorequiredCore functionality is a custom Django model field. Version 3.4.0 supports Django 6.0.
Agent activity
16 hits · last 30 days
node
14
Resources