How to change the name of a Django app?

New in Django 1.7 is a app registry that stores configuration and provides introspection. This machinery let’s you change several app attributes.

The main point I want to make is that renaming an app isn’t always necessary: With app configuration it is possible to resolve conflicting apps. But also the way to go if your app needs friendly naming.

As an example I want to name my polls app ‘Feedback from users’. It goes like this:

Create a apps.py file in the polls directory:

from django.apps import AppConfig

class PollsConfig(AppConfig):
    name = 'polls'
    verbose_name = "Feedback from users"

Add the default app config to your polls/__init__.py:

default_app_config = 'polls.apps.PollsConfig'

For more app configuration: https://docs.djangoproject.com/en/1.7/ref/applications/

In case you are using PyCharm and project stops working after rename:

1. Edit Run/Debug configuration and change environment variable DJANGO_SETTINGS_MODULE, since it includes your project name.
2. Go to Settings / Languages & Frameworks / Django and update the settings file location.

Re-migrate approach for a cleaner plate.

This can painlessly be done IF other apps do not foreign key models from the app to be renamed. Check and make sure their migration files don’t list any migrations from this one.

1. Backup your database. Dump all tables with a) data + schema for possible circular dependencies, and b) just data for reloading.
2. Run your tests.
3. Check all code into VCS.
4. Delete the database tables of the app to be renamed.
5. Delete the permissions: delete from auth_permission where content_type_id in (select id from django_content_type where app_label = '<OldAppName>')
6. Delete content types: delete from django_content_type where app_label = '<OldAppName>'
7. Rename the folder of the app.
8. Change any references to your app in their dependencies, i.e. the app’s views.py, urls.py , ‘manage.py’ , and settings.py files.
9. Delete migrations: delete from django_migrations where app = '<OldAppName>'
10. If your models.py ‘s Meta Class has app_name listed, make sure to rename that too (mentioned by @will).
11. If you’ve namespaced your static or templates folders inside your app, you’ll also need to rename those. For example, rename old_app/static/old_app to new_app/static/new_app.
12. If you defined app config in apps.py; rename those, and rename their references in settings.INSTALLED_APPS
13. Delete migration files.
14. Re-make migrations, and migrate.
15. Load your table data from backups.

Fun problem! I’m going to have to rename a lot of apps soon, so I did a dry run.

This method allows progress to be made in atomic steps, to minimise disruption for other developers working on the app you’re renaming.

See the link at the bottom of this answer for working example code.

1. Prepare existing code for the move:
   • Create an app config (set name and label to defaults).
   • Add the app config to INSTALLED_APPS.
   • On all models, explicitly set db_table to the current value.
   • Doctor migrations so that db_table was “always” explicitly defined.
   • Ensure no migrations are required (checks previous step).

2. Change the app label:

   • Set label in app config to new app name.
   • Update migrations and foreign keys to reference new app label.
   • Update templates for generic class-based views (the default path is <app_label>/<model_name>_<suffix>.html)

   • Run raw SQL to fix migrations and content_types app (unfortunately, some raw SQL is unavoidable). You can not run this in a migration.

     UPDATE django_migrations
        SET app = 'catalogue'
      WHERE app = 'shop';
     
     UPDATE django_content_type
        SET app_label = 'catalogue'
      WHERE app_label = 'shop';
     

   • Ensure no migrations are required (checks previous step).

3. Rename the tables:
   • Remove “custom” db_table.
   • Run makemigrations so django can rename the table “to the default”.
4. Move the files:
   • Rename module directory.
   • Fix imports.
   • Update app config’s name.
   • Update where INSTALLED_APPS references the app config.
5. Tidy up:
   • Remove custom app config if it’s no longer required.
   • If app config gone, don’t forget to also remove it from INSTALLED_APPS.

---

Example solution: I’ve created app-rename-example, an example project where you can see how I renamed an app, one commit at a time.

The example uses Python 2.7 and Django 1.8, but I’m confident the same process will work on at least Python 3.6 and Django 2.1.

Why not just use the option Find and Replace. (every code editor has it)?

For example Visual Studio Code (under Edit option):

You just type in old name and new name and replace everyhting in the project with one click.

NOTE: This renames only file content, NOT file and folder names. Do not forget renaming folders, eg. templates/my_app_name/ rename it to templates/my_app_new_name/

If you use Pycharm, renaming an app is very easy with refactoring(Shift+F6 default) for all project files.
But make sure you delete the __pycache__ folders in the project directory & its sub-directories. Also be careful as it also renames comments too which you can exclude in the refactor preview window it will show you.
And you’ll have to rename OldNameConfig(AppConfig): in apps.py of your renamed app in addition.

If you do not want to lose data of your database, you’ll have to manually do it with query in database like the aforementioned answer.

In many cases, I believe @allcaps’s answer works well.

However, sometimes it is necessary to actually rename an app, e.g. to improve code readability or prevent confusion.

Most of the other answers involve either manual database manipulation or tinkering with existing migrations, which I do not like very much.

As an alternative, I like to create a new app with the desired name, copy everything over, make sure it works, then remove the original app:

1. Start a new app with the desired name, and copy all code from the original app into that. Make sure you fix the namespaced stuff, in the newly copied code, to match the new app name.

2. makemigrations and migrate. Note: if the app has a lot of foreign keys, there will likely be issues with clashing reverse accessors when trying to run the initial migration for the copied app. You have to rename the related_name accessor (or add new ones) on the old app to resolve the clashes.

3. Create a data migration that copies the relevant data from the original app’s tables into the new app’s tables, and migrate again.

At this point, everything still works, because the original app and its data are still in place.

4. Now you can refactor all the dependent code, so it only makes use of the new app. See other answers for examples of what to look out for.

5. Once you are certain that everything works, you can remove the original app. This involves another (schema) migration.

This has the advantage that every step uses the normal Django migration mechanism, without manual database manipulation, and we can track everything in source control. In addition, we keep the original app and its data in place until we are sure everything works.

Simple 4 steps to rename an existing app in Django project without any pain or data loss.

Step 1

Rename the app folder. For this example,"old_app" is our old name and "new_app" is our new name".

mv ./old_app ./new_app

Step 2

Update all imports referencing the old folder to reference the new.

For example:

# Before 
from myproject.old_app import models

# After
from myproject.new_app import models

Step 3

Update old app name references within the Django migrations.

Example changes you’ll likely have to make:

# Before

dependencies = [
    ('old_app', '0023_auto_20200403_1050'),
]

# After

dependencies = [
    ('new_app', '0023_auto_20200403_1050'),
]

# Before

field = models.ForeignKey(
    default=None, on_delete=django.db.models.deletion.CASCADE,
    to='old_app.Experiment'
)

# After

field = models.ForeignKey(
    default=None, on_delete=django.db.models.deletion.CASCADE,
    to='new_app.Experiment'
)

Step 4

Make a commit at this point.

Then, however you run your application migrations in a deployed environment, run django_rename_app before you run your migrations in that process.

i.e Before "python manage.py migrate –noinput", as the example below shows.

# Before

python manage.py collectstatic --noinput
python manage.py migrate --noinput
gunicorn my_project.wsgi:application

# After

python manage.py collectstatic --noinput
python manage.py rename_app old_app new_app
python manage.py migrate --noinput
gunicorn my_project.wsgi:application

This will update the app name in the following internal Django database tables:

• django_content_type
• django_migrations

And rename the prefix of all of your tables to start with your new app name, rather than the old one.

That’s it.

Note : Its better to use your IDE’s/text editor’s find & replace function for making changes in the various files.

My simple alternative that avoids manual database manipulation (similar to https://stackoverflow.com/a/64133141/1608851), works well in a CI/CD, and is reversible.

1. Create an empty migration in the "old" app that renames the tables, content type, and migration records. Include a reverse migration.
   Example:

from django.db import migrations

sql = """
ALTER TABLE oldapp_examplemodel RENAME TO newapp_examplemodel;
UPDATE django_migrations SET app ='newapp' WHERE app ='oldapp';
UPDATE django_content_type SET app_label ='newapp' WHERE app_label ='oldapp';
"""

reverse_sql = """
ALTER TABLE newapp_examplemodel RENAME TO oldapp_examplemodel;
UPDATE django_migrations SET app ='oldapp' WHERE app ='newapp';
UPDATE django_content_type SET app_label ='oldapp' WHERE app_label ='newapp';
"""


class Migration(migrations.Migration):

    dependencies = [
        ('oldapp', '0001_initial'),
    ]

    operations = [
        migrations.RunSQL(sql, reverse_sql)
    ]

2. Set the model table name to the new_app.
   Example:

class ExampleModel(models.Model):

    # normal column definitions...

    class Meta:
        db_table = "newapp_examplemodel"  # add this line to the meta class

3. Commit, test, and deploy the above changes.
4. Delete the migration created in step 1.
5. Rename/move the old app and fix all references (see https://stackoverflow.com/a/8408131/1608851 for more details), including references in migrations.
6. Remove the db_table overrides from the model meta classes.
7. Commit, test, and deploy.

Notes:

• The django_migrations table will retain a row with the old app, because that row is added after our new migration was run, but before it was registered under the new app name. It should be okay to leave that as is.
• Deleting the migration is due to the above point, but also to prevent future issues when reverse migrating, but also because
• Reversing this app rename requires checking out / deploying the commit from step 3, then reversing our migration, then checking out / deploying the commit before that