Django Clone

5.5.0 · active · verified Fri Apr 17

django-clone is a Django library that facilitates the creation of a deep clone of a Django model instance, including its related objects (Foreign Keys, One-to-One, Many-to-Many). It handles unique fields and provides flexibility for custom attribute overrides during cloning. The current version is 5.5.0, and it maintains an active development pace with regular updates.

Common errors

```
IntegrityError: duplicate key value violates unique constraint "appname_modelname_fieldname_key"
```
cause Attempting to clone an instance where a field with `unique=True` is not overridden, leading to a duplicate value.

fix Pass a new unique value for the conflicting field using the `attrs` argument: `clone_instance(original_instance, attrs={'unique_field': 'new_unique_value'})`.
```
AttributeError: module 'django_clone' has no attribute 'clone_model_instance'
```
cause This typically occurs when upgrading to `django-clone` 5.0.0 or later and still using the old import path and function name.

fix Update your import statement from `from django_clone.utils import clone_model_instance` to `from django_clone import clone_instance`.
```
AttributeError: 'Manager' object has no attribute 'clone_instance'
```
cause The `clone_instance` function expects a model *instance* as its first argument, not a QuerySet manager (e.g., `MyModel.objects`).

fix Call `clone_instance` on an actual model instance, e.g., `my_instance = MyModel.objects.get(pk=1)`; then `clone_instance(my_instance, ...)`.

Warnings

breaking The main cloning function `clone_model_instance` was renamed to `clone_instance` and moved from `django_clone.utils` to the top-level `django_clone` package in version 5.0.0.
Fix: Update your imports from `from django_clone.utils import clone_model_instance` to `from django_clone import clone_instance`.
breaking The `shallow` parameter of the cloning function was removed in version 5.0.0. Deep cloning of related objects is now the default behavior, and granular control is managed via `attrs` and signals.
Fix: Remove the `shallow` parameter from your `clone_instance` calls. If you need to prevent certain fields or relations from being cloned, use the `attrs` dictionary to set specific values or handle relationships manually after the clone operation, or use the provided signals for more advanced customization.
gotcha Cloning an instance with `unique=True` fields will raise an `IntegrityError` if the unique field's value is not overridden or set to `None` (if nullable) in the `attrs` argument.
Fix: Always provide new unique values for unique fields via the `attrs` dictionary when cloning. For example: `clone_instance(original, attrs={'unique_field': 'new_unique_value'})`.
gotcha By default, `django-clone` attempts to deep clone related objects (ForeignKey, OneToOne, ManyToMany). While powerful, this can lead to unintended duplication if you meant to link to existing related objects or if the related objects themselves have complex unique constraints.
Fix: Review the cloning behavior for related objects. If you need to link to existing related instances instead of creating new ones, or if related objects have unique constraints, you must manage these explicitly via the `attrs` dictionary, setting the ForeignKey/OneToOne field to an existing instance, or handle ManyToMany fields post-cloning. Use the `pre_clone_instance` and `post_clone_instance` signals for advanced control.

Install

pip install django-clone Install stable version

Imports

clone_instance
wrong:
```
from django_clone.utils import clone_model_instance
```
correct:
```
from django_clone import clone_instance
```
The function was renamed from `clone_model_instance` to `clone_instance` and moved to the top-level package in version 5.0.

Quickstart

This example demonstrates how to clone a Django model instance using `clone_instance`. It creates a `Book` instance with a `ForeignKey` to `Author`, then clones the book, overriding the `isbn` (which is unique) and `title` to avoid conflicts. Note: A minimal Django setup is included for standalone runnability; in a real Django project, you'd omit `os.environ.setdefault` and `django.setup()`.

import os
from django.db import models
from django_clone import clone_instance

# Minimal Django setup for runnable example
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
import django
django.setup()

class Author(models.Model):
    name = models.CharField(max_length=100)

    def __str__(self):
        return self.name

class Book(models.Model):
    title = models.CharField(max_length=100)
    isbn = models.CharField(max_length=13, unique=True, null=True, blank=True)
    description = models.TextField(blank=True)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books')

    def __str__(self):
        return self.title

# Create some initial instances
author1 = Author.objects.create(name="Jane Doe")
original_book = Book.objects.create(
    title="The Original Story", 
    isbn="1234567890123", 
    description="A timeless classic.", 
    author=author1
)

# Clone the book instance, providing a new unique ISBN
cloned_book = clone_instance(original_book, attrs={'isbn': '9876543210987', 'title': 'The Cloned Story'})

print(f"Original Book: {original_book.title} (ISBN: {original_book.isbn}, Author: {original_book.author.name})")
print(f"Cloned Book: {cloned_book.title} (ISBN: {cloned_book.isbn}, Author: {cloned_book.author.name})")

view raw JSON →