Name the main command django

Django Internals
1

I suggest that we add a django command as an alias for django-admin. This will make tools like uvx django startproject work, as well as make it a bit easier with tools like pipx.

I’d also like for us to add configuration to pyproject.toml to get the default settings module from the pyproject.toml. This will allow django (and django-admin) to replace python manage.py when it has been configured.

For both of these suggestions, you can take a look at @jeff 's django-cli-no-admin that only adds the alias or my django-cmd that also adds the configuration option.

Depending how fully committed we are to it, we could also update the docs to reflect the new name of django-admin, or update the docs to suggest the new command instead of python manage.py. We could even change the default template to no longer include the manage.py script at all, although when I once attempted that on my Heroku project I found that the buildpack depended on the presence of the manage.py to determine it was a Django project and automatically call collectstatic.

When I started down this road 10 years ago, I met some resistance and I didn’t push it, so I want to make sure I gather some community consensus on the right thing to do before I jump ahead to doing it. Which of the suggestions would you like to see Django do Right Now?

  1. Add a django command as an alias of django-admin.
  2. Add configuration to pyproject.toml for the settings module.
  3. Switch docs to use django instead of django-admin.
  4. Switch docs to use configured django instead of python manage.py.
  5. Switch the default template to no longer include python manage.py.

Historical references:

22 Likes
2

I’d very much like to see this happen.

Another benefit would be to remove the confusion between django-admin and Django Admin.

About Heroku, we could update the buildpack to use the django command if available instead of looking for a manage.py file.

3 Likes
3

All of them! Great suggestions, bring ‘em on.

2 Likes
4

Thanks for kicking this off @ryanhiebert. Seeing both Jeff’s and your projects reminded me this is an annoying oddity and pain point.

When starting Boost Your Django DX a few years ago, I nearly started down the path of recommending python -m django and aliasing it as dj. But I realized it is a bit unfamiliar and may skip customizations in manage.py. Yet such customizations are a bit of an anti-pattern, even an attractive nuisance, because other ways to run Django projects skip it, such as through a WSGI server.

The rise of uv does make uvx and uv run very convenient ways to run things. I think it would be good to keep with the times. uv run -m django does work, but the -m` is an extra thing to remember.

IMO, having “yet another way” of doing things isn’t a huge concern, if we keep the other ways around, except possibly manage.py as you suggest.

Yes, this is probably a big one.

Here are my current feelings:

+1

+1 if we can make startproject create a corresponding pyproject.toml file. If we add the option but don’t create/update a file, it seems like we’d leave new manage.py-less projects settings-less. They would need manual editing before any further commands, which isn’t beginner-friendly or smooth.

Updating an existing pyproject.toml seems quite difficult since it requires an extra dependency to write TOML (tomli-w or similar). But it would be needed when passing a directory that contains one, especially like:

django startproject example .

(. being the current dir)

+1

+1 if we can figure out creating/updating pyproject.toml in startproject.

+1 if we can figure out creating/updating pyproject.toml in startproject, and if we implement a “deprecation” path. Too many beginner tutorials and books will be “broken” in an early step due to lack of the file.

For a “deprecation” pathway, we could make the default template print a short message like “Prefer the ‘django’ command or ‘python -m django’.”. This could go through the normal deprecation timeline, sticking around for two versions before removal. I grant it would be annoying, but I think easy enough to grasp and either remove the line from manage.py or update one’s practices.

6 Likes
5

For clarity, was this about dropping the manage.py, or adding the configuration, which is what you quoted? I agree with your concerns, but if it takes longer to get the default template worked out I’d still like the configuration available sooner.

6

FWIW, PyCharm’s Django integration relies on knowing the path to manage.py. I’m in favor of 1-5, but we might want to coordinate 5 (removing manage.py) with JetBrains and other tools.

1 Like
7

My own feeling is that switching the docs away from python manage.py needs to happen after or when we get the default template figured out, but that just adding the configuration in pyproject.toml could be merged earlier.

8

I’d be an extremely strong -1 against this.

I hate to even think of all the scripts, internal docs, and tooling that we have built around the management commands being executed by manage.py, and I’m having a hard time identifying a reason why it should be removed.

2 Likes
9

I think the plan could be amended this way:

  1. Switch docs to use configured django instead of python manage.py.
  2. Switch the default template to include a manage.py that just launches django (meaning it’s not reading the DJANGO_SETTINGS_MODULE environment variable anymore).
  3. Way in the future, if/when we feel the community at large is ready, switch the default template to no longer include python manage.py.
4 Likes
10

As an extra requirement, I would suggest that if this gets approved that a issue & PR is raised on django-upgrade to allow developers to easily make the switch when upgrading.

1 Like
11

It would be sensible update the default template to add the necessary configuration to pyproject.toml without removing manage.py. Deletions are scarier than additions, and the manage.py is a firmly rooted tradition that we may desire a longer transition time for.

I’d still prefer that we go ahead and plan to remove it with the normal deprecation policy the way that Adam has suggested, but I very much understand skepticism at removing something so traditional and visible to Django, and that has become a de-facto standard interface for Django.

The value that I’m chasing with that opinion is to minimize what’s included for a new project. Django unfortunately has quite a few of these types of little details, and if we want to continue to be the right place for new developers to get started, we need to prioritize making things as simple as possible. Having files that don’t serve a purpose for most new users seems unwise.

1 Like
12

Uh… I don’t think django-upgrade could do anything except delete manage.py, which would be too disruptive since it would break any scripts using it. What were you thinking?

13

Right, fair. We can add the option to read the configuration without adjusting the startproject template - that would come later.

14

Ah ok, possibly updating pyproject.toml or creating one if it doesn’t exist?

15

Tickets:

16

Hello @ryanhiebert,

Thank you for your enthusiasm and for following the recommended process to start this discussion — it’s much appreciated!

While I’ve seen the positive feedback, I think 2 days to consider this as finalized might be too short. We’ll need at least a couple of weeks to gather enough input, especially with the holidays coming up and many people taking time off.

For now, we’ll need to mark the tickets as wontfix until we’ve had time to gather more feedback. Specifically regarding the rename of the django-admin command, I have several questions that I’d like to organize and address clearly. However, due to other priorities, I’m unable to do that at the moment. I promise to share my thoughts soon – hopefully before the end of the year, but if not, then for sure after the 5.2 feature freeze.

Thanks for your understanding!

1 Like
17

I think number 1 and 3 would be fine. Typing django rather than django-admin seems like a win. That also seems to be what went down well on social media after @jeff’s recent post, and discussion following from that.

I have no desire to drop the manage.py helper.

I agree with the comments that it would be highly disruptive. Yes, if you (some combination of) install your app into your virtual environment, make sure you’re in the right cwd and set your PYTHONPATH correctly, you don’t need it, but I think grok-ing all of that is a significant step up from just “use manage.py from the project folder”.

To this day, I almost always use the manage.py helper when working with an existing project, rather than the django module (or admin script alias). I wouldn’t want to remove it.

1 Like
18

I’m a fan of #1 and #3 too.

You are right, Carlton, that the itch I’m scratching is s/django-admin/django/. Once a project is set up, I use python -m manage and I suspect uv run -m manage over django-admin, but maybe because python -m django is less obvious.

The rest need a little time to bake for me. I think some pyproject.toml support is interesting, but I also use ENV variables first which has less of a place in pyproject.toml because my local, testing, ci, and deployment ENVs change with some sensible fallbacks. I’m not against pyproject.toml support, but I’m just not sure what those options are yet or how they’d help me.

3 Likes
19

@jeff I don’t have a grand unified vision for replacing settings.py with pyproject.toml. Like you, I read from environment variables for configuration, and I do that in settings.py. There could be something worthwhile down the road to put more in pyproject.toml, but I don’t yet have much idea what that could be, and I’m not ready to spitball that yet.

Letting Django have a default settings module configured in a standard file without requiring a wrapper script still seems like a good step forward to me, though, and I’m having trouble thinking of why we might regret it. The long-standing most likely regret was that we’d choose the wrong file to put it in, but pyproject.toml seems pretty great.

20

I’m totally fine with not jumping to removing anything, it’s a big change. But you don’t need to understand all those details to get it working like manage.py. What we need to do is read the settings module from configuration (pyproject.toml, and we can include it in the default template) and set the python path the same way python does when you run python manage.py. I’ve done both of those with django-cmd, and with just configuring the settings file I no longer need to use manage.py at all. I’ve found it to be quite pleasant to use, and a shorter command to type as a bonus.

I want to get the django command merged, but I’ll admit that I’d be a bit bummed if we didn’t also find a way to configure the default settings module other than environment variables or a custom manage.py script.