--- name: remove-model description: Step-by-step guide for removing an existing model from NetBox, covering all required touch points in safe deletion order (tests, docs, nav, search, GraphQL, API, views, URLs, forms, filterset, table, choices, model, migration). Use when the user asks to remove, delete, or deprecate a model or object type from NetBox. --- # Removing a Model from NetBox Removing a model requires undoing ~13 components. Work in the order below — remove consumers before providers to avoid import errors during the process. Deleting a model is **irreversible once migrated**; confirm with the user before running `makemigrations`. ## 0. Before You Start Identify: - **Model name** and **app** — e.g. `MyModel` in `dcim` - **All references** — run a broad grep before touching anything: ```bash grep -r 'MyModel\|mymodel\|my-model\|my_model' netbox/ --include='*.py' -l grep -r 'MyModel\|mymodel\|my-model\|my_model' docs/ -l grep -r 'mymodel\|my-model' netbox/netbox/navigation/ --include='*.py' ``` Check for: - Other models with ForeignKey / M2M pointing to this model (they need updating or their own removal first) - Generic relations via `FeatureQuery` or `ContentType` that reference this model - Any plugin or external code documented as depending on this model **Do not proceed if other retained models have non-nullable FKs to this model** — those FK fields must be removed or made nullable first. ## 1. Remove Tests Delete test methods or entire test classes that exist solely for this model. If the test file contains only this model's tests, delete the file; otherwise remove just the relevant class(es). Files to check: - `netbox//tests/test_api.py` - `netbox//tests/test_views.py` - `netbox//tests/test_filtersets.py` - `netbox//tests/test_models.py` - `netbox//tests/test_forms.py` - `netbox//tests/test_tables.py` - Any app-specific test modules (e.g. `test_cablepaths.py`) ## 2. Remove Documentation 1. Delete `docs/models//.md`. 2. Remove the `mkdocs.yml` entry under the relevant `nav:` group. 3. Remove the entry from `docs/development/models.md` (the "Models Index" list). ## 3. Remove Navigation Menu Entry **File:** `netbox/netbox/navigation/menu.py` Remove the `get_model_item('', 'mymodel', ...)` line from the relevant `MenuGroup`. ## 4. Remove from Search Index **File:** `netbox//search.py` Delete the `@register_search` class for the model. If the file becomes empty (no other indexes), delete the file itself. ## 5. Remove GraphQL Remove in this order (schema depends on types, types depend on filters): 1. **`netbox//graphql/schema.py`** — remove the `my_model` and `my_model_list` fields from the app's `Query` type. 2. **`netbox//graphql/types.py`** — remove the `MyModelType` class and its `__all__` entry. 3. **`netbox//graphql/filters.py`** — remove the `MyModelFilter` class and its `__all__` entry. If any remaining type in `types.py` has a lazy annotation referencing `MyModelType`, remove that annotation too. ## 6. Remove REST API 1. **`netbox//api/urls.py`** — remove the `router.register('my-models', ...)` line. 2. **`netbox//api/views.py`** — remove the `MyModelViewSet` class. 3. **`netbox//api/serializers_/.py`** — remove the serializer class. If this was the only serializer in the module, delete the file and remove its `from . import *` line from `serializers_/__init__.py`. Also check other serializers that reference this model (e.g. `MyModelSerializer(nested=True)` on related serializers) and remove those fields too. ## 7. Remove URL Routes **File:** `netbox//urls.py` Remove the two `path(...)` entries that call `get_model_urls('', 'mymodel', ...)`. ## 8. Remove Views **File:** `netbox//views.py` Remove all view classes decorated with `@register_model_view(MyModel, ...)`. There are typically seven: - `MyModelListView` - `MyModelView` - `MyModelEditView` - `MyModelDeleteView` - `MyModelBulkImportView` - `MyModelBulkEditView` - `MyModelBulkDeleteView` - `MyModelBulkRenameView` (if present) Also remove the panel class from `netbox//ui/panels.py` and any `layout` references using it. If there is a model-specific HTML template (`netbox/templates//mymodel.html` or similar), delete it. ## 9. Remove Table **File:** `netbox//tables/.py` Remove the `MyModelTable` class. If it is the sole table in the module, delete the file and clean up the `__init__.py` re-export. **File:** `netbox//tables/__init__.py` Remove the corresponding `from . import *` or named import. ## 10. Remove Forms Remove in dependency order (bulk forms depend on the model form): 1. **`netbox//forms/bulk_import.py`** — remove `MyModelImportForm`. 2. **`netbox//forms/bulk_edit.py`** — remove `MyModelBulkEditForm`. 3. **`netbox//forms/filtersets.py`** — remove `MyModelFilterForm`. 4. **`netbox//forms/model_forms.py`** — remove `MyModelForm`. 5. **`netbox//forms/__init__.py`** — remove all re-exports of the deleted form classes. ## 11. Remove FilterSet **File:** `netbox//filtersets.py` Remove the `MyModelFilterSet` class. Also remove any imports of `MyModel` or related models that were only used by this filterset. ## 12. Remove Choices **File:** `netbox//choices.py` Remove any `ChoiceSet` subclasses that were defined exclusively for this model (e.g. `MyModelStatusChoices`). Leave choices that are shared with other models. ## 13. Remove the Model **File:** `netbox//models/.py` (or `models.py`) 1. Delete the `MyModel` class. 2. Remove `'MyModel'` from `__all__` in the module. 3. Remove the import line in `netbox//models/__init__.py` if this was the last model in the submodule (or remove just the `MyModel` name from a `from . import ...` line). 4. Remove any now-unused imports in the model file itself. ## 14. Generate the Migration **Do NOT write migrations manually.** Tell the user to run: ```bash cd netbox/ python manage.py makemigrations -n remove_mymodel --no-header ``` Set `DEVELOPER = True` in `configuration.py` if the command is blocked. Review the generated migration before applying — it should only contain a `DeleteModel` operation (plus any `RemoveField` operations for FKs on other models if Django detected them). Apply with: ```bash python manage.py migrate ``` ## Common Gotchas - **Remove consumers before providers** — tests, docs, GraphQL schema, API viewset, URL routes, and views all reference the model; remove them before removing the model itself to avoid import errors. - **FK cleanup** — Django will detect FKs pointing at the deleted model and auto-add `RemoveField` operations to the migration. Verify the migration is correct before running it. - **ContentType cleanup** — after migrating, `ContentType` rows for the old model linger in the database. They are harmless but can be cleaned up with `python manage.py remove_stale_contenttypes`. - **`__all__` entries** — grep all `__init__.py` files for the model name after removing the class; dangling re-exports cause `ImportError` at startup. - **Serializer references** — other serializers may have a nested `MyModelSerializer(nested=True)` field. Search for the serializer class name as well as the model name. - **`manage.py` lives in `netbox/`**, not the repo root. - **No `ruff format`** on existing files — use `ruff check` only. ## Summary Checklist | # | File(s) | Action | |---|---|---| | 1 | `tests/test_*.py` | Remove test classes for this model | | 2 | `docs/models//.md`, `mkdocs.yml`, `docs/development/models.md` | Delete doc page; remove nav entries | | 3 | `netbox/netbox/navigation/menu.py` | Remove `get_model_item(...)` line | | 4 | `/search.py` | Remove `SearchIndex` class | | 5 | `/graphql/schema.py`, `types.py`, `filters.py` | Remove query fields, type, filter | | 6 | `/api/urls.py`, `views.py`, `serializers_/.py` | Remove router entry, viewset, serializer | | 7 | `/urls.py` | Remove `get_model_urls(...)` paths | | 8 | `/views.py`, `/ui/panels.py` | Remove all view classes and panel | | 9 | `/tables/.py`, `tables/__init__.py` | Remove table class and re-export | | 10 | `/forms/*.py`, `forms/__init__.py` | Remove all four form classes and re-exports | | 11 | `/filtersets.py` | Remove `FilterSet` class | | 12 | `/choices.py` | Remove model-specific `ChoiceSet` subclasses | | 13 | `/models/.py`, `models/__init__.py` | Remove model class and `__all__` entry | | 14 | (user runs) | `makemigrations -n remove_mymodel --no-header` then `migrate` | ## References - Model base classes: `netbox/netbox/models/__init__.py` - Navigation menu: `netbox/netbox/navigation/menu.py` - `add-model` skill: `.claude/skills/add-model/SKILL.md` (reverse of this skill)