pip-prune 0.1.0
A lightning-fast Python CLI that scans your code and optimizes requirements.txt
License: MIT
Requires Python: >=3.9

<!--
SEO Meta Description: pip-prune is a lightning-fast Python CLI tool to automatically clean, optimize, and pin your requirements.txt. Remove unused dependencies, pin versions, and keep your Python projects secure and reproducible. Ideal for CI/CD, open source, and professional Python development.
Keywords: python dependency cleaner, requirements.txt optimizer, python package audit, remove unused python packages, pin python dependencies, python requirements hygiene, python dependency management, python security, python reproducibility
-->

# pip-prune 🧹 — Optimize Your Python requirements.txt Automatically

![pip-prune demo](pip-prune.gif)

*Demo: pip-prune scanning and optimizing a Python project*

**pip-prune** is a blazing-fast, zero-dependency Python CLI tool that scans your project, detects which packages in `requirements.txt` are actually used, and rewrites the file to the smallest, version-pinned, lint-clean set. 

- **Remove unused dependencies**
- **Pin versions for reproducibility**
- **Catch dynamic imports with runtime tracing**
- **Beautiful, colorized terminal output**
- **CI/CD and GitHub Actions ready**

---

## 🚀 Use Case: Python Dependency Hygiene & Security

**pip-prune** is perfect for:
- Python developers who want to keep their `requirements.txt` minimal and accurate
- Teams enforcing dependency hygiene in CI/CD
- Open source maintainers who want reproducible, clean installs
- Anyone who wants to avoid dependency bloat and security risks

**Keywords:** python dependency cleaner, requirements.txt optimizer, remove unused python packages, pin python dependencies, python dependency hygiene, python requirements audit, python security, python reproducibility

---

## ⚡ Installation (pip)

```bash
pip install pip-prune
```

---

## 🛠️ Command Usage & Examples

### 1. Scan for Used Imports
```bash
pip-prune scan --paths src
```
- Lists all detected imports in your codebase.

### 2. Rewrite requirements.txt (Dry Run)
```bash
pip-prune rewrite --paths src --dry-run
```
- Shows what would be removed/kept, but does not modify files.

### 3. Actually Rewrite requirements.txt
```bash
pip-prune rewrite --paths src --no-dry-run --yes --inline
```
- Removes unused packages, pins versions, and updates your file (with backup).

### 4. Check for Unused Dependencies (CI/CD)
```bash
pip-prune check --paths src
```
- Exits 1 if changes are needed, 0 if clean (great for GitHub Actions).

### 5. Runtime Tracing for Dynamic Imports
```bash
pip-prune scan --paths src python3 main.py
```
- Runs your command and catches imports loaded at runtime (e.g., plugins, lazy imports).

### 6. Ignore Rules
```bash
pip-prune rewrite --ignore numpy,rich --dry-run
```
- Always keep specified packages, even if unused.

### 7. Config File Support
Create `.pipprunerc.toml`:
```toml
[pip-prune]
paths = ["src"]
ignore = ["numpy"]
tracer = false
```
Then run:
```bash
pip-prune rewrite --config .pipprunerc.toml --dry-run
```

---

## 📦 Example Workflow

1. **Install:**
    ```bash
    pip install pip-prune
    ```
2. **Scan your project:**
    ```bash
    pip-prune scan --paths myproject
    ```
3. **Optimize requirements.txt:**
    ```bash
    pip-prune rewrite --paths myproject --no-dry-run --yes --inline
    ```
4. **Add to CI:**
    ```yaml
    - name: Check requirements
      run: pip-prune check --paths myproject
    ```

---

## 🧪 Testing & Development

- **Run all tests:**
    ```bash
    pytest
    ```
- **Type checking:**
    ```bash
    mypy pip_prune/
    ```
- **Linting:**
    ```bash
    ruff check .
    black --check .
    ```
- **Build for PyPI:**
    ```bash
    python -m build
    ```

---

## 🌟 Features
- Lightning-fast static AST scan
- Optional runtime tracing for dynamic imports
- Import-to-package resolution with heuristics
- Pretty Rich terminal output (color, icons, tables)
- Ignore rules via CLI, config, or env
- Config file support (`pyproject.toml`, `.pipprunerc.toml`)
- CI/CD and GitHub Actions ready
- 100% typed, mypy/ruff/black/isort clean
- Cross-platform: Linux, macOS, Windows (Python 3.9+)

---

## 📈 Why pip-prune?
- **Save time:** No more manual dependency audits
- **Reduce risk:** Fewer attack surfaces, less bloat
- **Reproducibility:** Pin exact versions for every install
- **DevX:** Beautiful, actionable output

---

## 📄 License
MIT — see [LICENSE](LICENSE)

---

## 👤 Author & Contact
**Author:** Sherin Joseph Roy  
**Email:** sherin.joseph2217@gmail.com  
**GitHub:** [Sherin-SEF-AI/pip-prune](https://github.com/Sherin-SEF-AI/pip-prune.git)

---

**pip-prune: The fastest way to keep your Python dependencies clean, safe, and minimal.**