minport
A Python linter that finds unnecessarily long import paths and suggests shorter alternatives by tracing re-export chains.
The Problem
Python packages expose public APIs through re-exports, but developers often import from deep internal paths instead of the canonical public interface:
# Unnecessarily long — these reach into internal modules
from pydantic.fields import FieldInfo
from sqlalchemy.orm.session import Session
from myproject.domain.user.models import User
# Shorter — these use the public re-export path
from pydantic import FieldInfo
from sqlalchemy.orm import Session
from myproject.domain import User
Long import paths are:
- Harder to read: Internal paths obscure the public interface
- Fragile: Internal paths break when package maintainers refactor internals (re-exports are the stable API)
- Inconsistent: Same name imported from different paths across the codebase
Installation
pip install minport
# or with uv
uv add --dev minport
# or with pipx (for global CLI usage)
pipx install minport
Requirements: Python 3.11+ / No runtime dependencies.
Quick Start
minport check src/
# src/models.py:3:1: MP001 `from pydantic.fields import FieldInfo` can be shortened to `from pydantic import FieldInfo`
# Found 1 error (checked 12 files, 1 fixable with `minport check --fix`).
minport check src/ --fix
# Found 1 error (checked 12 files, fixed 1 in 1 file).
Usage
minport check src/ # Check a directory
minport check src/models.py # Check a single file
minport check src/ --src src/ # Set import resolution root
minport check src/ --exclude "tests/*" # Exclude patterns (overrides defaults)
minport check src/ --extend-exclude "generated/*" # Add to default excludes
minport check src/ --config path/to/pyproject.toml # Custom config path
minport check src/ --fix # Auto-fix in place
minport check src/ --quiet # Suppress the summary line
minport check src/ --output-format github # output for github annotations
minport check src/ --no-cache # Disable the persistent cache for this run
Exit codes: 0 = no violations, 1 = violations found, 2 = error (e.g. path not found).
Configuration
Configure minport in pyproject.toml:
[tool.minport]
src = ["src"] # Import resolution root(s)
exclude = ["tests/*", "migrations/*"] # Exclude patterns (overrides defaults)
extend-exclude = ["generated/*"] # Add patterns without overriding defaults
CLI arguments override pyproject.toml settings.
Default Excludes
minport automatically skips common non-source directories (.venv, __pycache__, .git, node_modules, dist, site-packages, etc.). Use --exclude to override these defaults entirely, or --extend-exclude to add patterns on top of them.
Environment Variables
| Variable | Effect |
|---|---|
MINPORT_NO_CACHE=1 |
Skip the persistent find_spec cache (same as --no-cache). |
MINPORT_CACHE_DIR=<path> |
Override the cache root. Defaults to $XDG_CACHE_HOME/minport or ~/.cache/minport. |
XDG_CACHE_HOME=<path> |
Standard XDG base dir; minport stores the cache under <path>/minport. |
The persistent cache is invalidated by content hash of the project's lock file (uv.lock, poetry.lock, Pipfile.lock, requirements.lock, requirements.txt, or pyproject.toml — first one found, in that order). Changing dependencies switches the cache to a fresh file; the previous one is left untouched.
Rules
| Code | Name | Description | Fixable |
|---|---|---|---|
| MP001 | shorter-import-available | A shorter import path is available via re-exports | Yes |
Inline Suppression
Add # minport: ignore to suppress violations on specific imports.
Single-line import:
from pydantic.fields import FieldInfo # minport: ignore
Multi-line import — suppress all names:
from pydantic.fields import ( # minport: ignore
FieldInfo,
Field,
)
Multi-line import — suppress a specific name:
from pydantic.fields import (
FieldInfo, # minport: ignore ← only FieldInfo is suppressed
Field, # ← this can still be flagged
)
How It Works
For each from X.Y.Z import Name:
- Decompose the module path:
[X, X.Y, X.Y.Z] - For each candidate path (shortest first), check if
Nameis re-exported there - Re-export detection via AST analysis of
__init__.py:from .submodule import Name— explicit re-exportfrom .submodule import Name as Name— PEP 484 explicit formfrom .submodule import *— wildcard (recursively resolved, respects__all__)__all__ = ["Name", ...]— public API declaration
- Return the shortest match (if shorter than the original)
Works with both project packages (analyzes __init__.py files) and third-party packages (uses importlib.util.find_spec + AST analysis, no runtime imports).
Safety
- No modifications without
--fix: Read-only by default - Collision detection: If a name exists in multiple candidate paths, the import is not flagged
- Syntax error tolerance: Malformed Python files are skipped with a warning
--fixwrites in place: Always verify changes withgit diffbefore committing
Integrations
pre-commit
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: minport
name: minport
entry: minport check
language: python
types: [python]
additional_dependencies: ["minport"]
GitHub Actions
# .github/workflows/lint.yml
jobs:
minport:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.13"
- uses: actions/cache@v4
with:
path: ~/.cache/minport
key: minport-${{ runner.os }}-${{ hashFiles('**/uv.lock') }}
restore-keys: minport-${{ runner.os }}-
- run: pip install minport
- run: minport check src/ --output-format github
The --output-format github flag emits GitHub Actions workflow commands, so violations appear as inline annotations on the PR file view. The actions/cache step persists ~/.cache/minport across runs so the second invocation skips re-resolving third-party packages.
Limitations
- Only rewrites
from X.Y.Z import Name(notimport X.Y.Z) - Does not analyze dynamic or runtime imports
- No IDE integration yet
Contributing
git clone https://github.com/KinjiKawaguchi/minport.git
cd minport
uv sync
uv run pytest --cov=minport
uv run ruff check src/ tests/
- DeepWiki — AI-generated codebase documentation
License
Metadata
Release files for minport 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| minport-0.3.1.tar.gz | 181.1 kB | With provenance | Details for minport-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| minport-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for minport-0.3.1-py3-none-any.whl |
Total release size: 214.1 kB
Release files / minport-0.3.1.tar.gz
| Download URL | minport-0.3.1.tar.gz |
|---|---|
| Size | 181.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc66509ce9bb780cd86380ee42153002fd92c0bb81e5450992fa9c8d24bc06b5
|
|
BLAKE2b-256 checksum How to use checksums |
fab64dfea3a9a6b129206bbfae011c2db6ed6c3cff1262b4174c8feb787ee6df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 11, 2026.
Transparency logRelease files / minport-0.3.1-py3-none-any.whl
| Download URL | minport-0.3.1-py3-none-any.whl |
|---|---|
| Size | 33.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2696177a2be7983837c740788ce68376095f8b28cc9ccfa4ce4ddcb45f3dbade
|
|
BLAKE2b-256 checksum How to use checksums |
8494d5212c36b4ea9a58c040692d76dbb01fb6df723017e79c98822382227443
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 11, 2026.
Transparency logSecurity for minport 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for minport-0.3.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.