---
id: django-deprecate-fields
version: "0.2.3"
license: Apache License 2.0
license_treatment: permissive
maintenance: active
---

# django-deprecate-fields — This package allows deprecating model fields and allows removing them in a backwards compatible manner.

License: permissive · Maintenance: active · Downloads: 2.8M/mo

## What it is and what it does

Django-deprecate-fields provides a decorator-based approach to safely remove model fields from a Django application without breaking existing code during the transition period. When you wrap a field with `deprecate_field()`, the package automatically converts it to nullable during the next migration, and any code accessing the field will receive None instead of raising an error. This allows you to deploy the deprecation marker, run migrations, then safely remove the field definition in a subsequent deployment—a three-step process that maintains backward compatibility across your application.

The package is designed for teams managing long-lived Django projects where fields need to be retired gradually. It handles the common Django commands (makemigrations, migrate, showmigrations) automatically, and supports custom migration commands via a settings parameter. With a single runtime dependency on Django and no known vulnerabilities, it integrates cleanly into existing projects.

Use it for:

- Mark a database column as deprecated in one release, allowing code to stop using it before physical removal in a later release.
- Provide a default return value (via `return_instead` argument) when deprecated fields are accessed, easing the transition for legacy code.
- Coordinate field removal across multiple services by using the three-step deprecation workflow without requiring simultaneous deployments.
- Audit which parts of your codebase still reference deprecated fields by catching None returns or custom fallback values.
- Support custom migration tools (e.g., pgmakemigrations) by configuring DEPRECATE_FIELD_CUSTOM_MIGRATION_COMMAND in settings.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a decorator to mark Django model fields as deprecated, automatically making them nullable and returning None on access, enabling safe field removal across deployments.

Yes. This package solves a real operational problem—removing Django model fields safely across multiple deployments—with low install friction, active maintenance, and no security issues. It is most valuable for teams managing production Django applications where coordinated deployments are difficult or where you need to support older code during a transition period. If you rarely remove fields or always deploy atomically, the benefit is lower.

## Install

pip install django-deprecate-fields
uv add django-deprecate-fields
poetry add django-deprecate-fields

## Installing django-deprecate-fields

Before you install: Low friction install with a single runtime dependency on Django. Actively maintained with a recent commit and no known vulnerabilities.

License in practice: Released under Apache License 2.0, a permissive license allowing commercial use with minimal restrictions.

Quickstart:

pip install django-deprecate-fields

from django_deprecate_fields import deprecate_field
from django.db import models

class MyModel(models.Model):
    field1 = deprecate_field(models.CharField())
    field2 = models.CharField()

Verify before relying:

- Whether the package works with Django versions released after 3.1, given classifiers only list up to 3.1
- Whether Python 2.7 support is actively maintained or a legacy artifact

## Package facts

- License: Apache License 2.0 (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 2.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django model field deprecation, safely remove django fields, backward compatible field removal, django migration field deprecation, gradual field removal django, django-migrations, field-deprecation, backward-compatibility

[View on SkillFed](https://skillfed.io/packages/django-deprecate-fields) · [View on PyPI](https://pypi.org/project/django-deprecate-fields/)