Python Module Completion for Zsh

A zsh plugin that provides intelligent tab completion for python -m commands with hierarchical module navigation and smart project detection.

Features

• Immediate Completion: Works with both python -m<TAB> and python -m <TAB>
• Hierarchical Navigation: Navigate through nested modules with tab completion (e.g., my_package.submodule.deeper)
• Smart Project Detection: Automatically detects Python projects via virtual environments, __init__.py files, and project configuration files
• Cross-Platform: Works on Linux, macOS, and other Unix-like systems
• Intelligent Filtering: Excludes virtual environments and build directories from completion
• Smart Suffix Handling: Modules with submodules complete without space, final modules complete with space

Installation

Manual Installation

1. Clone this repository:

   git clone https://github.com/UshioA/zsh-python-module-completion.git ~/.zsh/zsh-python-module-completion

2. Add to your .zshrc:

   source ~/.zsh/zsh-python-module-completion/python-module-completion/python-module-completion.plugin.zsh

3. Restart your shell or run exec zsh

Oh My Zsh

1. Clone into Oh My Zsh custom plugins directory:

   git clone https://github.com/UshioA/zsh-python-module-completion.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-python-module-completion

2. Add to your plugins in .zshrc:

   plugins=(... zsh-python-module-completion)

3. Restart your shell

Zinit

Add to your .zshrc:

zinit light UshioA/zsh-python-module-completion

Antigen

Add to your .zshrc:

antigen bundle UshioA/zsh-python-module-completion

Zplug

Add to your .zshrc:

zplug "UshioA/zsh-python-module-completion"

Usage

In any Python project, use tab completion with python -m:

# Basic completion (both work)
python -m<TAB>           # Shows available top-level modules  
python -m <TAB>          # Shows available top-level modules

# Hierarchical navigation  
python -m mypackage<TAB>       # Completes to mypackage (no space if has submodules)
python -m mypackage.<TAB>      # Shows submodules in mypackage
python -m mypackage.sub<TAB>   # Completes to mypackage.sub
python -m mypackage.sub.<TAB>  # Shows modules in sub

Example

For a project structure like:

my_project/
├── my_module/
│   ├── __init__.py
│   ├── sub_module/
│   │   ├── __init__.py
│   │   └── deep_module.py
│   └── utils.py
└── setup.py

Tab completion works as:

1. python -m <TAB> → my_module
2. python -m my_module<TAB> → my_module (no space, has submodules)
3. python -m my_module.<TAB> → sub_module, utils
4. python -m my_module.sub_module.<TAB> → deep_module

Activation

Important: This plugin only activates when you create a .local_module_completion file in your Python project root. This ensures that zsh's default Python completion (including all command-line options and module completion) continues to work normally in directories without this marker file.

To enable local module completion for a project:

# In your project root directory
touch .local_module_completion

Without this file, the plugin completely defers to zsh's built-in Python completion, preserving all standard completion behavior including:

• Command-line options (python -<TAB> shows -c, -m, -V, etc.)
• Module completion after -m (lists installed packages from your Python environment)

Project Detection

When the .local_module_completion file is present, the plugin detects Python projects by looking for:

• Virtual environments (venv, .venv, env, .env)
• Python project files (pyproject.toml, setup.py, requirements.txt, Pipfile, poetry.lock)
• Package directories (containing __init__.py)