Python Dependency Conflict Checker - Check before you install
PyConflict answers one critical question: "Will adding this package break my environment?"
Unlike existing tools that detect conflicts after installation, PyConflict is proactive - it checks dependencies before making changes.
The Problem:
$ pip install django==3.2
# ... 5 minutes later ...
ERROR: django 3.2 requires asgiref>=3.3.2,<4
but channels 4.0 requires asgiref>=3.5.0
# Time wasted: 15-30 minutes debuggingThe Solution:
$ pyconflict check-add django==3.2
✗ Cannot add django==3.2
Conflicts detected:
• asgiref
Required: >=3.3.2,<4
Installed: 3.7.2
Suggestions:
→ Upgrade django to 4.2+ (compatible with channels 4.0)- ✅ Proactive conflict detection - Check before installing
- ✅ AI-assistant friendly - JSON output for Claude Code, Cursor, etc.
- ✅ Fast - Aggressive caching (<3s cached, <10s uncached)
- ✅ Direct dependencies - Checks package's immediate dependencies
- ✅ Latest stable version - Find the newest non-prerelease version
- Phase 2: Platform markers, extras handling, MCP server for Claude Code
- Phase 3: Transitive dependency checking, CI/CD integration
pip install pyconflict# Check latest version
$ pyconflict check-add tensorflow
# Check specific version
$ pyconflict check-add django==3.2
# JSON output (for AI tools)
$ pyconflict check-add requests --json# Latest version
$ pyconflict stable pandas
# Filter by Python version
$ pyconflict stable numpy --python-version 3.8Check if adding a package will cause conflicts with your current environment.
pyconflict check-add <package> [OPTIONS]Options:
--version TEXT- Specific version to check--json- Output in JSON format--deep- Check transitive dependencies (Phase 3)
Exit codes:
0- Safe to add, no conflicts1- Conflict detected2- Package not found4- Repository error5- Unexpected error
Examples:
# Safe to add
$ pyconflict check-add fastapi
✓ Safe to add fastapi==0.104.1
Confidence: 90%
# Conflict detected
$ pyconflict check-add django==3.2
✗ Cannot add django==3.2
Conflicts detected:
• asgiref
Required: >=3.3.2,<4
Installed: 3.7.2
Suggestions:
→ Upgrade django to 4.2+ (compatible with channels 4.0)
# JSON output
$ pyconflict check-add django==3.2 --json
{
"status": "conflict",
"exit_code": 1,
"package": {
"name": "django",
"version": "3.2.0"
},
"conflicts": [
{
"dependency": "asgiref",
"required": ">=3.3.2,<4",
"installed": "3.7.2",
"required_by": "django==3.2.0",
"severity": "error"
}
],
"suggestions": [
"Upgrade django to 4.2+ (compatible with channels 4.0)"
],
"confidence": 0.9,
"caveats": [
"Only direct dependencies checked (not transitive)",
"Platform-specific markers not evaluated",
"Optional extras not included"
]
}Get the latest stable (non-prerelease) version of a package.
pyconflict stable <package> [OPTIONS]Options:
--python-version TEXT- Filter by Python version compatibility--json- Output in JSON format
Examples:
$ pyconflict stable pandas
pandas==2.1.4
$ pyconflict stable numpy --python-version 3.8
numpy==1.24.4 (filtered by Python version)PyConflict is designed to be called by AI coding assistants:
# Claude internally runs:
result=$(pyconflict check-add tensorflow --json)
exit_code=$?
if [ $exit_code -eq 0 ]; then
echo "tensorflow==2.15.0" >> requirements.txt
else
# Show conflict to user
echo "Cannot add tensorflow: conflicts detected"
fiAdd to .cursor/rules:
Before adding Python packages:
1. Run: pyconflict check-add <package> --json
2. Only proceed if exit_code == 0
PyConflict follows Clean Architecture principles:
┌─────────────────────┐
│ CLI (Typer) │ ← Presentation Layer
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Use Cases │ ← Application Layer
│ • CheckAddPackage │
│ • GetLatestStable │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Domain Services │ ← Domain Layer
│ • ConflictDetector │
│ • VersionResolver │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Infrastructure │ ← Infrastructure Layer
│ • PyPI Repository │
│ • Disk Cache │
│ • Pip Environment │
└─────────────────────┘
Key benefits:
- Testable: Domain logic has zero external dependencies
- Swappable: Can replace PyPI with private registry without touching business logic
- Maintainable: Clear boundaries prevent spaghetti code
# Clone the repository
git clone https://github.com/alimoradi296/pyconflict.git
cd pyconflict
# Install in development mode
pip install -e ".[dev]"# Run all tests
pytest
# Run with coverage
pytest --cov=pyconflict --cov-report=html
# Run specific test
pytest tests/unit/domain/test_version_resolver.py# Format code
black src tests
# Lint
ruff src tests
# Type check
mypy srcPyConflict MVP focuses on direct dependencies only. The following are Phase 2/3 features:
- ❌ Platform markers not evaluated - May miss platform-specific dependencies
- ❌ Extras not checked -
package[security]extras are ignored - ❌ Transitive dependencies not checked - Only direct dependencies analyzed
- ❌ Dynamic dependencies - Install-time determined deps cannot be predicted
Confidence Score: 90% for direct dependencies
- Direct dependency conflict detection
- Latest stable version lookup
- CLI with JSON output
- Basic caching
- Platform marker support (PEP 508)
- Extras handling
- MCP server for Claude Code
- Enhanced error messages
- Transitive dependency checking (--deep flag)
- CI/CD integration examples
- Python API
- Configuration file support
Q: How is this different from pip check?
A: pip check is reactive - it checks for conflicts after installation. PyConflict is proactive - it checks before you install.
Q: Does it work with private PyPI repositories? A: Not in MVP. Phase 2 will add support for private registries.
Q: Can it automatically fix conflicts? A: No. PyConflict provides suggestions, but you decide what to do. Automatic fixes are too risky.
Q: How accurate is it? A: 90%+ for direct dependencies (MVP scope). Phase 2 will add platform/extras support (85% accuracy).
Q: Does it replace poetry/pip-tools? A: No. PyConflict is a checker, not a package manager or lock file tool. Use it alongside your existing tools.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
MIT License - see LICENSE for details.
- GitHub: https://github.com/alimoradi296/pyconflict
- PyPI: https://pypi.org/project/pyconflict/
- Documentation: https://pyconflict.readthedocs.io
- Issues: https://github.com/alimoradi/pyconflict/issues
Built with:
Made with ❤️ for Python developers and AI coding assistants