# Should management command verbosity levels be labelled?

**URL:** <https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783>\
**Category:** Django Internals\
**Created:** [December 22, 2025, 1:36pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783 "2025-12-22T13:36:47Z")\
**Posts on this page:** 12\
**Page:** 1

<div class="post-metadata">

**Author:** ![Mah-Rye-Kuh](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mah-rye-kuh/32/18416_2.png) [@Mah-Rye-Kuh](https://forum.djangoproject.com/u/Mah-Rye-Kuh)\
**Post date:** [December 22, 2025, 1:36pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/1 "2025-12-22T13:36:47Z")

</div>

The default verbosity levels of Django management commands are magic numbers; should those values be mapped to an object?

* * *

**Context:**

Django’s management commands provide each command with an [optional verbosity argument](https://docs.djangoproject.com/en/dev/ref/django-admin/#cmdoption-verbosity) with allowed values ranging from `0` to `3`.

Each number represents a level which is described in the help function for commands, but not in the command class themselves: it is up to the developer to determine which output belongs to which level.

I personally found it more descriptive to map the values to sensibly named constants—or even better, an `Enum`—to remove some of the guesswork of what each level represents.

* * *

**Code:**

The `manage. py help` command provides this explanation for the available verbosity levels:

```shell
-v, --verbosity {0,1,2,3}
    Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output

```

Which you could map to an enum like so:

```python
from enum import IntEnum

class Verbosity(IntEnum):
    """Verbosity level corresponding to Django management command defaults."""

    MINIMAL_OUTPUT = 0
    NORMAL_OUTPUT = 1
    VERBOSE_OUTPUT = 2
    VERY_VERBOSE_OUTPUT = 3

```

* * *

What do you think?

_NB. I expected there to already be a topic about this subject but could not find it. If this has already been discussed before, please feel free to share the relevant link._

---

<div class="post-metadata">

**Author:** ![KenWhitesell](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/kenwhitesell/32/280_2.png) [@KenWhitesell](https://forum.djangoproject.com/u/KenWhitesell)\
**Post date:** [December 22, 2025, 3:31pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/2 "2025-12-22T15:31:55Z")

</div>

`<opinion>`  
As an addition or supplement to using the numbers, I guess I wouldn’t see an issue with that. (I can’t see me ever using them, but I acknowledge it can be considered a personal choice.)

I can’t see myself implementing them by name in the management commands that I create, nor would I envision myself implementing tests for them in my code, which means I’d be expecting Django to convert the names to numbers in the argument values passed to the handler.

As a replacement, I would be strongly against it, as it would create an uncommon convention for specifying levels.

In fact, if a change were to be made here, I’d prefer going in the other direction.

There are a number of linux commands that use repeated instances of `-v`, and/or patterns of `-v`, `-vv`, `-vvv` to identify the level of verbosity. (Some that I can think of right off-hand include tar, ssh, tcpdump, and pip.)

If any change were to be made, my preference would be to adhere more to the existing conventions rather that implementing something new.

Side note: POSIX doesn’t address this issue, merely to say that different levels of verbosity are program-specific - which also means that it’s valid to create a non-sequential set of verbosity levels. There’s nothing saying that the output of `-vv` or `-v 2` must include the output of `-v`, although that does appear to be true for all examples I can think of.  
`</opinion>`

---

<div class="post-metadata">

**Author:** ![jacobtylerwalls](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/jacobtylerwalls/32/30603_2.png) [@jacobtylerwalls](https://forum.djangoproject.com/u/jacobtylerwalls)\
**Post date:** [December 22, 2025, 8:12pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/3 "2025-12-22T20:12:17Z")

</div>

I assumed the proposal only related to `call_command()` usage, not command-line usage, but that may have been a premature assumption!

---

<div class="post-metadata">

**Author:** ![nanorepublica](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/nanorepublica/32/14211_2.png) [@nanorepublica](https://forum.djangoproject.com/u/nanorepublica)\
**Post date:** [December 22, 2025, 8:18pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/4 "2025-12-22T20:18:30Z")

</div>

+1 for the simple fact that ruff complains about ‘magic’ numbers so in a custom management command having this available would be clearer in that code:  
ie instead of

```python
...
if verbosity >= 1:
...

```

having:

```auto
...
if verbosity >= Verbosity.NORMAL_OUTPUT:
...

```

---

<div class="post-metadata">

**Author:** ![adamchainz](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/adamchainz/32/26_2.png) [@adamchainz](https://forum.djangoproject.com/u/adamchainz)\
**Post date:** [January 2, 2026, 9:41am UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/5 "2026-01-02T09:41:42Z")

</div>

+1 from me. I believe we will need an IntEnum to avoid breaking existing code. Let’s keep the names short: Verbosity.MINIMAL etc.

---

<div class="post-metadata">

**Author:** ![Mah-Rye-Kuh](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mah-rye-kuh/32/18416_2.png) [@Mah-Rye-Kuh](https://forum.djangoproject.com/u/Mah-Rye-Kuh)\
**Post date:** [January 4, 2026, 12:43pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/6 "2026-01-04T12:43:22Z")

</div>

> I assumed the proposal only related to `call_command()` usage, not command-line usage, but that may have been a premature assumption!

This assumption is correct; my recommendation is for Python code only.

I like Ken’s proposal as well, but that would be a separate discussion and lead to a possibly breaking change for existing management command calls.

---

<div class="post-metadata">

**Author:** ![Mah-Rye-Kuh](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mah-rye-kuh/32/18416_2.png) [@Mah-Rye-Kuh](https://forum.djangoproject.com/u/Mah-Rye-Kuh)\
**Post date:** [January 5, 2026, 11:33am UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/7 "2026-01-05T11:33:45Z")

</div>

> [@adamchainz](#):
>
> Let’s keep the names short: Verbosity.MINIMAL etc.

Like so then?

```python
from enum import IntEnum

class Verbosity(IntEnum):
    MINIMAL = 0
    NORMAL = 1
    VERBOSE = 2
    VERY_VERBOSE = 3

```

---

<div class="post-metadata">

**Author:** ![Mah-Rye-Kuh](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mah-rye-kuh/32/18416_2.png) [@Mah-Rye-Kuh](https://forum.djangoproject.com/u/Mah-Rye-Kuh)\
**Post date:** [January 5, 2026, 11:53am UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/8 "2026-01-05T11:53:16Z")

</div>

I created a GitHub ticket based off this idea:

> <https://github.com/django/new-features/issues/106>
>
> \### Code of Conduct
> 
> \- \[x\] I agree to follow Django's Code of Conduct
> 
> \### Featu…re Description
> 
> Create an (int) enum for verbosity options in Django management commands.
> 
> This would be an optional feature for those who prefer a mapped value over a magic number. It would only affect Python code, as an add-on, and would not break existing management calls.
> 
> \### Problem
> 
> There is currently no default mapping for verbosity levels: only the numbers 0 to 4 are provided via the default management command option \`verbosity\`.
> 
> Using numbers directly does not clarify their meaning. They also trigger "magic number" warnings in linters.
> 
> Providing a standardized mapping in Django Core would:
> 
> 1. More clearly define the meaning of each value.
> 2. Make verbosity-based if-statements more descriptive code.
> 3. Allow reusability of the values in documentation and tutorials.
> 4. Fix magic number warnings in linters and code other quality checkers.
> 5. Prevent developers from having to define such an enum themselves in their projects.
> 
> \### Request or proposal
> 
> request
> 
> \### Additional Details
> 
> Originally posted on the Django Forum: \[Should management command verbosity levels be labelled?\](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783).
> 
> \### Implementation Suggestions
> 
> Based on the current levels described in management help commands, the enum could look like this:
> 
> \`\`\`python
> from enum import IntEnum
> 
> 
> class Verbosity(IntEnum):
> MINIMAL = 0
> NORMAL = 1
> VERBOSE = 2
> VERY\_VERBOSE = 3
> \`\`\`
> 
> Names chosen per the help output for the verbosity argument:
> 
> \`\`\`sh
> \-v, --verbosity {0,1,2,3}
> Verbosity level; 0=minimal output, 1=normal output, 2=verbose output, 3=very verbose output
> \`\`\`

---

<div class="post-metadata">

**Author:** ![whyscream](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/whyscream/32/29418_2.png) [@whyscream](https://forum.djangoproject.com/u/whyscream)\
**Post date:** [April 1, 2026, 3:00pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/9 "2026-04-01T15:00:14Z")

</div>

The existence of such an Enum wouldn’t really help me implement logging, as I still need to reinvent all the other parts for useful logging. I always expect Django to actually do something useful with the `-v` flag by itself, as it provides the flag out of the box, but it doesn’t.

E.g. When using default Python logging in management commands and called libraries, the logger adheres to the settings in Django’s `settings.LOGGING` dict, and to me it seems intuitive that a management command called with `-v 3` will switch (for the output of that command) the log level to `logging.DEBUG`.

Unfortunately the current implementation doesn’t do anything useful, depending solely on the command implementor who has to re-invent the wheel somehow. While a generic interface is available in the CLI (raising end-user expectations), this results in many different verbosity-handling implementations, or no implementation at all (most of the time). As an end-user, that annoys me to no end, and as a developer I always (ok, sometimes) need to think up some way to use this flag: there’s no obvious or preferred, documented approach. Over the years I might have created a dozen slightly different ways to handle this.

The fact that the numeric values don’t naturally map to Python’s `logging` log levels as they have opaque descriptions, doesn’t really help of course. All of this results in many ‘verbose-ignorant’ command implementations.

My basic idea would be to implement in Django something like:

- Map `-v` values to Python log levels (e.g. 0 → `logging.WARNING`, 3 → `logging.DEBUG`).
- Automatically switch log level of the root level to the given verbosity.
- Promote use of the `logging` module in the management command documentation, and maybe some preferred way to combine it with `Command.stdout.write()`.

Would this be any good? Other ideas and suggestions welcome of course.

---

<div class="post-metadata">

**Author:** ![Mah-Rye-Kuh](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/mah-rye-kuh/32/18416_2.png) [@Mah-Rye-Kuh](https://forum.djangoproject.com/u/Mah-Rye-Kuh)\
**Post date:** [April 2, 2026, 1:28pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/10 "2026-04-02T13:28:10Z")

</div>

These are interesting points that warrant their own thread, as this thread is not about logging.

---

<div class="post-metadata">

**Author:** ![whyscream](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/whyscream/32/29418_2.png) [@whyscream](https://forum.djangoproject.com/u/whyscream)\
**Post date:** [April 6, 2026, 10:42pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/11 "2026-04-06T22:42:02Z")

</div>

Hi @Mah-Rye-Kuh , thanks for your reply. I guess you are correct, I’ll create a new thread. What triggered me to follow up here is probably the fact that you are interested to improve or simplify (and maybe standardize) how to use the existing `-v` flag in management commands, which is exactly what my post was about.

---

<div class="post-metadata">

**Author:** ![whyscream](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.djangoproject.com/whyscream/32/29418_2.png) [@whyscream](https://forum.djangoproject.com/u/whyscream)\
**Post date:** [April 12, 2026, 1:52pm UTC](https://forum.djangoproject.com/t/should-management-command-verbosity-levels-be-labelled/43783/12 "2026-04-12T13:52:50Z")

</div>

New thread in [Implement default handling of --verbosity in management commands](https://forum.djangoproject.com/t/implement-default-handling-of-verbosity-in-management-commands/44892)