manage_django_project

Helper to develop Django projects:

• Easy bootstrap a virtual environment:
  • Just get the sources and call ./manage.py
  • Only python3-pip and python3-venv package needed to bootstarp
• Alle Django manage commands useable as normal CLI and via cmd2 shell
• cmd2 shell with autocomplete of all existing manage commands and all options
• Auto switching Django settings between local and tests settings.
• Helpful manage commands for developing:

Included Django management commands:

• code_style - Check/Fix project code style
• coverage - Run tests with coverage and report
• install - Just install the project as editable via pip (Useful if version has been changed)
• make_messages - Make and compile locales message files
• nox - Run tests via nox
• pip_audit - Run pip-audit with configuration from pyproject.toml
• playwright - Call playwright CLI
• project_info - Information about the current Django project
• publish - Build a new release and publish it to PyPi
• run_dev_server - Setup test project and run django developer server
• shell - Go into cmd2 shell with all registered Django manage commands
• update_req - Update project requirements via uv
• update_test_snapshot_files - Update all snapshot files (by remove and recreate all snapshot files)
• uv_audit - Run uv audit with configuration from pyproject.toml

How to use it

Some steps are needed to use manage_django_project in your project.

Here a overview and below details:

• add manage_django_project to your dev dependencies
• You Django project should have separate settings for prod, local and tests (Last two ones are used by manage_django_project)
• Add the bootstrap manage.py
• Add a __main__.py with the execute_django_from_command_line() call.
• In your pyproject.toml:
  • Add the [manage_django_project] section
  • Add the __main__-file as [project.scripts]
• Add the name of your [project.scripts] into bootstrap manage.py

All examples below used manage_django_project_example. You have to rename this string/path to your Django package name.

Full example is here: https://github.com/jedie/manage_django_project/tree/main/manage_django_project_example

If everything works as expected you can just call the ./manage.py file and the magic happens ;)

main.py

Add a .../manage_django_project_example/__main__.py file, looks like:

from manage_django_project.manage import execute_django_from_command_line


def main():
    """
    entrypoint installed via pyproject.toml and [project.scripts] section.
    Must be set in ./manage.py and PROJECT_SHELL_SCRIPT
    """
    execute_django_from_command_line()


if __name__ == '__main__':
    main()

pyproject.toml

[project.scripts]
manage_django_project_example = "manage_django_project_example.__main__:main"

[manage_django_project]
module_name="your_project_example"

# Django settings used for all commands except test/coverage/nox:
local_settings='your_project.settings.local'

# Django settings used for test/coverage/nox commands:
test_settings='your_project.settings.tests'

./manage.py

Add a copy of manage.py file to your project source root.

Change only manage_django_project_example in this line:

PROJECT_SHELL_SCRIPT = BIN_PATH / 'manage_django_project_example'

Start hacking

Just clone the project and start ./manage.py to bootstrap a virtual environment:

# Install base requirements:
~$ sudo apt install python3-pip python3-venv

# Get the sources:
~$ git clone https://github.com/jedie/manage_django_project.git
~$ cd manage_django_project/

# Just call manage.py and the magic happen:
~/manage_django_project$ ./manage.py

# start local dev. web server:
~/django-for-runners$ ./manage.py run_dev_server

# run tests:
~/django-for-runners$ ./manage.py test
# or with coverage
~/django-for-runners$ ./manage.py coverage
# or via nox:
~/django-for-runners$ ./manage.py nox

Backwards-incompatible changes

v0.2.x -> v0.3.x

The config was moved out from __main__.py into pyproject.toml

You must add in your pyproject.toml the following stuff:

[manage_django_project]
module_name="your_project_example"

# Django settings used for all commands except test/coverage/nox:
local_settings='your_project.settings.local'

# Django settings used for test/coverage/nox commands:
test_settings='your_project.settings.tests'

The config argument was remove from execute_django_from_command_line(), so your __main__.py must look like:

from manage_django_project.manage import execute_django_from_command_line


def main():
    execute_django_from_command_line()


if __name__ == '__main__':
    main()

Make new release

We use cli-base-utilities to generate the history in this README.

To make a new release, do this:

• Increase your project version number
• Run tests to update the README
• commit the changes
• Create release

history

• v0.14.0
  • 2026-08-03 - fix test_project_info()
  • 2026-08-03 - +AGENTS.md
  • 2026-08-03 - Use always latest versions for local development
  • 2026-08-03 - Remove audit from Gitlab CI: This is a lib and not a project with a lock file
  • 2026-08-03 - NEW: uv audit
  • 2026-08-03 - Update nox config
  • 2026-08-03 - Update git pre commit versions
• v0.13.0
  • 2026-07-03 - Update test setup
  • 2026-07-03 - fix code styles
  • 2026-07-03 - Support newer cmd2 version
  • 2026-07-03 - Remove uv.lock because it's a library
• v0.12.0
  • 2026-02-06 - bugfix nox rerun
  • 2026-02-06 - Update to cmd2 v2.7 -> v3.2
  • 2026-01-30 - Update test matrix: Remove Django 5.1 and add 6.0
• v0.11.2
  • 2026-01-30 - Update CI config
  • 2026-01-30 - Bugfix tests around "pip-audit"
  • 2026-01-30 - Update requirements and apply manageprojects updates
  • 2025-11-28 - Update README.md
  • 2025-11-28 - Add logo
  • 2025-11-28 - Update tests and run configs
  • 2025-11-28 - Update requirements