Netbox migration process

[mikygee]

Hello,

I installed netbox first in version 4.1.3 and I move to 4.4.10

So far I have not met many problems however, there might be migration commands to add columns in the database when it's needed.

I tried everytime to use the migrate commands but it fails. Here from 4.4.10 to 4.5.0

# python3 netbox/manage.py migrate
/var/www/htdocs/applications/netbox-4.5.0/netbox/netbox/settings.py:236: UserWarning: API_TOKEN_PEPPERS is not defined. v2 API tokens cannot be used.
  warnings.warn("API_TOKEN_PEPPERS is not defined. v2 API tokens cannot be used.")
Operations to perform:
  Apply all migrations: account, auth, circuits, contenttypes, core, dcim, django_rq, extras, ipam, sessions, social_django, taggit, tenancy, thumbnail, users, virtualization, vpn, wireless
Running migrations:
  No migrations to apply.
  Your models in app(s): 'core' have changes that are not yet reflected in a migration, and so won't be applied.
  Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.

# python3 netbox/manage.py makemigrations
/var/www/htdocs/applications/netbox-4.5.0/netbox/netbox/settings.py:236: UserWarning: API_TOKEN_PEPPERS is not defined. v2 API tokens cannot be used.
  warnings.warn("API_TOKEN_PEPPERS is not defined. v2 API tokens cannot be used.")
CommandError: This command is available for development purposes only. It will
NOT resolve any issues with missing or unapplied migrations. For assistance,
please post to the NetBox discussion forum on GitHub:
    https://github.com/netbox-community/netbox/discussions

So what should I do with the migrate commands ?

[mr1716]

You need to define the API_TOKEN_PEPPERS value in your configuration.py. Check out the configuration_testing.py file here to help understand how to configure and set those values:: https://github.com/netbox-community/netbox/pull/20477/files

[mikygee]

Hello,

Thank you for your answer I added the API_TOKEN_PEPPERS token

However I don't know if i'm required to run this command or not

# python3 netbox/manage.py migrate
/var/www/htdocs/applications/netbox-4.5.0/venv/lib/python3.12/site-packages/urllib3/__init__.py:35: NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 4.1.0'. See: https://github.com/urllib3/urllib3/issues/3020
  warnings.warn(
Operations to perform:
  Apply all migrations: account, auth, circuits, contenttypes, core, dcim, django_rq, extras, ipam, sessions, social_django, taggit, tenancy, thumbnail, users, virtualization, vpn, wireless
Running migrations:
  No migrations to apply.
  Your models in app(s): 'core' have changes that are not yet reflected in a migration, and so won't be applied.
  Run 'manage.py makemigrations' to make new migrations, and then re-run 'manage.py migrate' to apply them.

Before that I did run this one
# ./upgrade.sh

[mr1716]

It wouldn’t hurt, probably be a good thing??

But if I solved the issue, you can mark the issue as resolved??

[mikygee]

Hello,

Actually my question was about the migrate command not about the token.
I didn't realise that I had a problem with the token and you helped with that, thank you.

So my question is, is it requiered to run this command when you migrate from one version to another
# python3 netbox/manage.py migrate
or this command is enough
# ./upgrade.sh

Regards

[mr1716]

Apologies for that. It would be a good idea to run the manage.py migrate script to ensure that the new migrations are properly added

[pheus]

Hi,

Sorry you’re running into this during the upgrade.

When you run ./upgrade.sh, it already performs the database migration step (python3 manage.py migrate) as part of the standard upgrade workflow (along with creating/updating the Python virtual environment, installing dependencies, collecting static files, etc.). So in normal circumstances, running ./upgrade.sh is enough.

Running python3 netbox/manage.py migrate manually afterwards also won’t hurt. Django keeps track of which migrations have already been applied and will simply report “No migrations to apply” when everything is up to date.

Also, makemigrations is not something you should run on a NetBox production install. NetBox ships with all required migrations, and makemigrations is intentionally disabled outside of development.

That said, this line is unexpected for an official NetBox release:

Your models in app(s): 'core' have changes that are not yet reflected in a migration

It usually indicates a mismatch between the code you’re running and the migration files (for example: local code changes, an incomplete/modified install, or running management commands with the wrong Python environment/venv).

To be sure you’re using the same virtual environment that upgrade.sh manages, you can either:

1. Run the command directly via the venv’s Python:

./venv/bin/python netbox/manage.py showmigrations core

2. Or “activate” the venv first, then run commands normally:

source ./venv/bin/activate
python3 netbox/manage.py showmigrations core
deactivate

Could you run one of the above and paste the output here (in a code block)?

[mikygee]

Hello,

Thank you for your answer.

Here's the command output

# python3 netbox/manage.py showmigrations core
/var/www/htdocs/applications/netbox-4.5.0/venv/lib/python3.12/site-packages/urllib3/__init__.py:35: NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 4.1.0'. See: https://github.com/urllib3/urllib3/issues/3020
  warnings.warn(
core
 [X] 0001_squashed_0005 (5 squashed migrations)
 [X] 0006_datasource_type_remove_choices
 [X] 0007_job_add_error_field
 [X] 0008_contenttype_proxy
 [X] 0009_configrevision
 [X] 0010_gfk_indexes
 [X] 0011_move_objectchange
 [X] 0012_job_object_type_optional
 [X] 0013_job_data_encoder
 [X] 0014_datasource_sync_interval
 [X] 0015_remove_redundant_indexes
 [X] 0016_job_log_entries
 [X] 0017_objectchange_message
 [X] 0018_concrete_objecttype
 [X] 0019_configrevision_active
 [X] 0020_owner

Thank you

[pheus]

Hi,

Thanks for sharing the output!

The good news is that all NetBox “core” migrations are marked as applied ([X] all the way through 0020_owner). So from Django’s perspective, there are no missing NetBox-provided migrations to apply.

That makes the earlier message…

Your models in app(s): 'core' have changes that are not yet reflected in a migration

…a bit unusual for an official NetBox release. In a “clean” install, the models and the shipped migrations should always align.

A few common causes are:

• A code mismatch (e.g. files from multiple NetBox versions mixed together, or some local modifications/patches to NetBox code).
• Running commands against the wrong tree/environment (e.g. invoking manage.py from one directory while Python is importing code from somewhere else on disk).
• An incomplete/overwritten upgrade (especially if upgrading by copying files over an existing directory).

Since your path looks like a release archive/extracted directory (not a git checkout), the easiest sanity check is often to ensure the install directory is pristine:

• Extract the NetBox release into a fresh new directory
• Copy over only what’s meant to persist (e.g. netbox/configuration.py, media/, and any local reports/ / scripts/)
• Re-run ./upgrade.sh

If you want to see exactly what Django thinks is “different” in core, you can also do a targeted diagnostic run of makemigrations (without actually creating anything):

1. Temporarily enable developer mode in your NetBox configuration (netbox/configuration.py):

DEVELOPER = True

2. Then run:

./venv/bin/python netbox/manage.py makemigrations core --dry-run --check -v 3

This won’t write migrations (because of --dry-run), but it will print the specific model changes Django is detecting. If you can paste that output here (in a code block), it should point us directly to what’s causing the mismatch.

(And once done, I’d recommend setting DEVELOPER = False again.)

[mikygee]

Thank you for your answer

I did a fresh install and just copied configuration.py and media/ reports/ scripts so I jumped to what you asked at the end

# ./netbox/manage.py makemigrations core --dry-run --check -v 3
/var/www/htdocs/applications/netbox-4.5.0/venv/lib/python3.12/site-packages/urllib3/__init__.py:35: NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 4.1.0'. See: https://github.com/urllib3/urllib3/issues/3020
  warnings.warn(
Migrations for 'core':
  netbox/core/migrations/0021_alter_datafile_hash.py
    ~ Alter field hash on datafile
Full migrations file '0021_alter_datafile_hash.py':
# Generated by Django 5.2.9 on 2026-01-13 23:29

import django.core.validators
from django.db import migrations, models


class Migration(migrations.Migration):

    dependencies = [
        ('core', '0020_owner'),
    ]

    operations = [
        migrations.AlterField(
            model_name='datafile',
            name='hash',
            field=models.CharField(editable=False, max_length=64, validators=[django.core.validators.RegexValidator(message='La longueur doit être de 64 caractères hexadécimaux.', regex='^[0-9a-f]{64}$')]),
        ),
    ]

I don't know how to interpret this but it seems it's related with the hash

[pheus]

Thank you very much for taking the time to troubleshoot this with me. That output is really helpful.

Based on the dry-run, Django is only detecting a change to the DataFile.hash field’s validator message (in your output it’s rendered in French: “La longueur doit être de 64 caractères hexadécimaux.”). Changing the configured language/locale should not result in Django thinking a new migration is needed, so this appears to be a NetBox/Django migration serialization issue (i.e., a false-positive “model changes” warning).

I was able to reproduce this on my side as well. I’ll open an issue so it can be tracked and propose a fix. In the meantime, you can safely ignore this: it does not affect the database schema or your NetBox data, and it shouldn’t impact normal operation. It’s mainly the warning that’s misleading.

Thanks again for your help!

[mikygee]

Hello,
Did you manage to open the issue related to this problem ?
Thank you

[pheus]

Hi @mikygee,

Yes, I opened an issue for this here: #21175.

Sorry for the confusion earlier; I misread your last comment and assumed you had already seen it. I’ve also submitted a fix, and it should be included in the next patch release once it’s released.

Thanks again for taking the time to report this and help with troubleshooting!

[mikygee]

Wow thank you very much for reproducing the problem and open the issue.

It's me who is thanking you.

Thank you to mr1716 as well

[mikygee]

Thank you