Introduction

Renaming a Django app is more than a directory rename. The app label appears in imports, configuration, migration metadata, and often in database table names, so a safe rename requires a deliberate sequence of code and schema changes.

Understand What Django Uses the App Name For

In a typical project, the app name appears in several places:

• The Python package directory.
• 'INSTALLED_APPS.'
• 'apps.py and the AppConfig.name value.'
• Import paths across the project.
• Migration dependencies.
• Generated table names, if you rely on Django defaults.

That means a rename can be easy in a fresh project and much harder in a production system with existing migrations and deployed data. If the app is not yet released, the simplest path is often to rename the package and regenerate migrations. If it is already live, plan the migration strategy first.

Rename the Package and App Configuration

Start by renaming the directory, then update the app config.

Suppose the current app is blog and the new name should be articles. Your structure changes from blog/ to articles/.

Update apps.py:

1from django.apps import AppConfig
2
3
4class ArticlesConfig(AppConfig):
5    default_auto_field = "django.db.models.BigAutoField"
6    name = "articles"

Then update INSTALLED_APPS in settings.py:

1INSTALLED_APPS = [
2    "django.contrib.admin",
3    "django.contrib.auth",
4    "django.contrib.contenttypes",
5    "django.contrib.sessions",
6    "django.contrib.messages",
7    "django.contrib.staticfiles",
8    "articles.apps.ArticlesConfig",
9]

If you used the shorter "blog" form before, changing to the explicit config path is clearer during the rename.

Fix Imports Across the Project

Next, update imports that still point to the old package name:

from articles.models import Post
from articles.views import PostListView

Common places to check:

• URL configuration files.
• Views, forms, serializers, and admin classes.
• Test modules.
• Management commands.
• Any third-party integration that imports the app directly.

A quick search for the old app name is essential, but do not blindly replace every string. Some references may be database labels, migration dependencies, or user-facing text that should remain unchanged.

Handle Migrations Carefully

This is the part that determines whether the rename is trivial or risky. Existing migrations refer to the old app label, and Django uses that label when tracking migration history.

For a new or disposable project, you can often:

1. Rename the app.
2. Delete old migrations.
3. Recreate migrations.
4. Rebuild the database.

For an existing deployed project, that approach is usually unacceptable. Instead, preserve the data and write explicit schema migrations if table names need to change.

Example migration for renaming a table:

1from django.db import migrations
2
3
4class Migration(migrations.Migration):
5    dependencies = [
6        ("articles", "0001_initial"),
7    ]
8
9    operations = [
10        migrations.RunSQL(
11            sql="ALTER TABLE blog_post RENAME TO articles_post;",
12            reverse_sql="ALTER TABLE articles_post RENAME TO blog_post;",
13        ),
14    ]

Whether this is required depends on how your models are configured. If you already set db_table explicitly, you may not need to rename the physical table at all.

Consider Keeping the Database Table Name Stable

Many teams rename the Django app code but keep the existing table names to reduce operational risk. You can do that by setting db_table explicitly:

1from django.db import models
2
3
4class Post(models.Model):
5    title = models.CharField(max_length=200)
6
7    class Meta:
8        db_table = "blog_post"

That approach avoids a production table rename, which may simplify deployment and rollback. The tradeoff is that the database keeps the old naming convention while the Python package uses the new one.

Validate the Rename Before Deployment

After updating the package, imports, and migration plan, run the normal Django checks:

1python manage.py makemigrations
2python manage.py migrate
3python manage.py check
4python manage.py test

Also open the admin site and a few key pages manually. A rename often breaks reverse imports, admin registration, or signal loading in ways that static review can miss.

If the app exposes URLs, verify that your root urls.py still imports the correct module:

1from django.urls import include, path
2
3urlpatterns = [
4    path("articles/", include("articles.urls")),
5]

Common Pitfalls

• Renaming the directory but forgetting AppConfig.name or INSTALLED_APPS.
• Replacing all occurrences of the old app name without checking migration dependencies.
• Renaming database tables in production when keeping the old db_table would have been safer.
• Assuming tests cover everything when admin registration or signal import order still depends on the old path.
• Treating a deployed app rename like a new-project cleanup instead of planning a real migration path.

Summary

• Renaming a Django app affects Python imports, settings, migrations, and often database naming.
• Start with the package rename, apps.py, and INSTALLED_APPS.
• Update imports carefully instead of doing a blind search-and-replace.
• Decide early whether database table names should change or remain stable.
• Test the renamed app with migrations, checks, and real application flows before deployment.