Install & Compatibility
Where this runs
tested against v1.1 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 82.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.3s · import 0.000s · 83MB
82MB installed
● package 82MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EncryptedCharField
✓ from django_cryptography.fields import EncryptedCharField
✗ from django_cryptography import EncryptedCharField
To get started, install the package, add `django_cryptography` to your `INSTALLED_APPS`, and configure the `DJANGO_CRYPTOGRAPHY_KEY` in your Django settings. This key must be a base64-encoded Fernet key, typically loaded from an environment variable for security. You can then use `EncryptedCharField` or `EncryptedTextField` in your models to automatically encrypt and decrypt data.
import os
# settings.py
INSTALLED_APPS = [
# ...
'django_cryptography',
]
# Generate a key once with: `from cryptography.fernet import Fernet; Fernet.generate_key().decode()`
# Set this as an environment variable, e.g., export DJANGO_CRYPTOGRAPHY_KEY='YOUR_GENERATED_KEY'
DJANGO_CRYPTOGRAPHY_KEY = os.environ.get('DJANGO_CRYPTOGRAPHY_KEY', '')
# myapp/models.py
from django.db import models
from django_cryptography.fields import EncryptedCharField
class SecretNote(models.Model):
title = models.CharField(max_length=100)
content = EncryptedCharField(max_length=500)
def __str__(self):
return self.title
# Example usage in a Django shell or view:
# from myapp.models import SecretNote
# note = SecretNote.objects.create(title='Top Secret', content='This is highly confidential information.')
# print(note.content) # decrypted value
# stored_value = SecretNote.objects.values_list('content', flat=True).get(pk=note.pk) # will be encrypted bytes
# print(f"Stored (encrypted): {stored_value}")
Debug
Known issues
breakingVersion 1.0 introduced significant breaking changes to key management. The `KEY_NAME` and `KEY_STORE` settings were removed, and the `DJANGO_CRYPTOGRAPHY_KEY` setting (loaded from an environment variable) became the sole method for providing the encryption key.fixMigrate your key management to use the `DJANGO_CRYPTOGRAPHY_KEY` environment variable. Generate a new Fernet key if you were using the old key generation methods, and update your `settings.py`.
affects: <1.0
breakingThe `KeyGeneratingEncryptedField` was removed in version 1.0, simplifying the API by making key management an application-level concern via settings.fixRemove `KeyGeneratingEncryptedField` usage from your models. Ensure `DJANGO_CRYPTOGRAPHY_KEY` is properly configured in your settings. If you need to generate a key, do so manually using `Fernet.generate_key()`.
affects: <1.0
gotchaThe `DJANGO_CRYPTOGRAPHY_KEY` must be a valid base64-encoded Fernet key. If it's missing, malformed, or doesn't match the key used for encryption, data will not be encrypted/decrypted correctly, leading to `InvalidToken` errors.fixEnsure `DJANGO_CRYPTOGRAPHY_KEY` is set correctly in your environment or `settings.py`. A valid key can be generated once with `from cryptography.fernet import Fernet; Fernet.generate_key().decode()`.
affects: All versions >=1.0
gotchaChanging an existing `CharField` or `TextField` to an `EncryptedCharField` or `EncryptedTextField` on a model with existing data requires a data migration to encrypt the old data. A simple `makemigrations` and `migrate` will not automatically encrypt existing plaintext data.fixManually create a data migration to iterate through existing records, decrypt (if necessary, e.g., if switching encryption libraries), and then re-save the data using the new encrypted field type. This will trigger the encryption on save.
affects: All versions
Upgrade
Version history
1.1latest on PyPI · released Apr 6, 2022
Audit
Dependencies
DjangorequiredCore framework for integration.
cryptographyrequiredProvides the underlying encryption primitives (Fernet).