https://github.com/soldatov-ss/django-completion
Tab completion for Django's manage.py — commands, app labels, options, and migration targets in bash and zsh
https://github.com/soldatov-ss/django-completion
autocomplete bash-completion developer-tools django manage-py python shell-completion tab-completion zsh-completion
Last synced: 3 days ago
JSON representation
Tab completion for Django's manage.py — commands, app labels, options, and migration targets in bash and zsh
- Host: GitHub
- URL: https://github.com/soldatov-ss/django-completion
- Owner: soldatov-ss
- License: mit
- Created: 2026-04-25T08:03:51.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-24T06:17:40.000Z (about 1 month ago)
- Last Synced: 2026-05-24T08:17:04.337Z (about 1 month ago)
- Topics: autocomplete, bash-completion, developer-tools, django, manage-py, python, shell-completion, tab-completion, zsh-completion
- Language: Python
- Homepage: https://soldatov-ss.github.io/django-completion/
- Size: 368 KB
- Stars: 32
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG/0.1.0.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# django-completion
Project-aware **tab completion** for Django's `manage.py`.
Press Tab to complete commands, app labels, options, and migration targets — in bash and zsh — from your actual Django project.
## Installation
Install it in the same environment as your Django project:
```bash
pip install django-completion
# or
uv add django-completion
```
Add the app:
```python
INSTALLED_APPS = [
...
"django_completion",
]
```
Install the shell hook:
```bash
python manage.py autocomplete install
```
Then restart your terminal or reload your shell config:
```bash
source ~/.bashrc # bash
source ~/.zshrc # zsh
```
## What Completes
Supported invocation styles:
```bash
manage.py
python manage.py
python3 manage.py
python ./manage.py
uv run python manage.py
```
Completion depth:
- command names after `manage.py`
- option flags for all commands; app labels for `migrate`, `check`, `dumpdata`, `test`, and `makemigrations`
- `migrate` app labels filtered to apps that have migrations
- migration names and `zero` after `python manage.py migrate app_label`
- option descriptions in zsh where available
Django's built-in completion covers command names and option flags — it has no knowledge of your app labels, migration names, or project-specific targets. django-completion fills that gap. See [comparison with Django's built-in completion](https://soldatov-ss.github.io/django-completion/comparison/) for a full feature breakdown.
## Commands
```bash
python manage.py autocomplete status
python manage.py autocomplete status --verbose
python manage.py autocomplete refresh
python manage.py autocomplete uninstall
```
`status --verbose` is the best first diagnostic when completion behaves unexpectedly. It reports the cache path, schema version, migration counts, warning count, shell hooks, installed script versions, and package version.
`refresh` rebuilds `.django-completion-cache.json` manually. The cache also refreshes automatically after `manage.py` commands with a 60-second cooldown. To disable auto-refresh:
```python
DJANGO_COMPLETION_AUTO_REFRESH = False
```
## Compatibility
| Area | Supported |
|---|---|
| Python | 3.10+ |
| Django | 4.2+ |
| Shells | bash, zsh |
| OS | Linux and macOS expected |
| Windows | not officially supported; WSL with bash/zsh may work |
| Invocations | `manage.py`, `python manage.py`, `python3 manage.py`, `python ./manage.py`, `uv run python manage.py` |
| Completion depth | commands, app labels, options, migrate app labels, migration names |
## Safety and Privacy
- No telemetry.
- No network calls.
- Tab completion reads only the local cache file.
- Tab completion does not import Django.
- Tab completion does not touch the database.
- The cache is local runtime state in the project root.
- The cache contains command names, app labels, option names/help, migration names, warnings, and timestamps.
- Shell rc edits are marker-delimited and reversible.
- `autocomplete uninstall` removes managed shell hooks and managed scripts.
- The package has no middleware, models, migrations, or request-time behavior.
For teams that prefer strict production settings:
```python
if DEBUG:
INSTALLED_APPS += ["django_completion"]
```
`DEBUG` is not always the right environment switch; separate settings modules or a custom environment flag may fit your deployment process better.
## Limitations
- bash and zsh only; fish is planned for a later release
- no `django-admin` support
- no official native Windows or PowerShell support
- no global options before command, such as `python manage.py --settings config.settings migrate`
- no custom alias support, such as `dj migrate`
- no database-aware applied/unapplied migration filtering
## Roadmap
Near-term candidates include more wrapper support, better Docker-oriented examples, fish shell support, and additional command-specific completion rules.
Long term, the goal is to learn from real-world usage and explore whether parts of this approach could inform Django's own management-command completion story.
## Documentation
Full documentation is at https://soldatov-ss.github.io/django-completion/.
## Development
```bash
git clone git@github.com:soldatov-ss/django-completion.git
cd django-completion
uv sync
uv run pytest -q
uv run ruff check .
uv run ty check
```
django-completion was created in 2026 by [Soldatov Serhii](https://github.com/soldatov-ss).