pipu-cli 1.0.0

A cute Python package updater

pipu

pipu is a smart Python package updater that safely upgrades your installed packages while respecting dependency constraints. It's like pip list --outdated + automated upgrades, but safe and easy.

Why pipu?

Keeping Python packages up-to-date is important, but upgrading packages manually is tedious and risky:

• Running pip install --upgrade for each package is time-consuming
• Upgrading one package might break others due to dependency constraints
• Hard to know which packages can be safely upgraded together

pipu solves these problems:

• Automatically finds all packages that can be safely upgraded
• Shows you exactly what will be upgraded before doing anything
• Upgrades everything in one command, letting pip handle the details
• Provides rollback capability if something goes wrong
• Beautiful terminal UI with progress indicators

Installation

pip install pipu-cli

Quick Start

The fastest way to upgrade all your packages:

pipu

This runs pipu upgrade — it checks for updates and upgrades everything safely.

Both pipu and pipu upgrade will:

1. Check all your installed packages
2. Find available updates (using cache if fresh, or fetching from PyPI)
3. Determine which ones are safe to upgrade
4. Show you a table of what will be upgraded
5. Ask for confirmation (press Y to proceed)
6. Upgrade everything safely

To preview what can be upgraded without installing anything:

pipu outdated

Example Session

$ pipu

Step 1/5: Inspecting installed packages...
  Found 182 installed packages

Step 2/5: Checking for updates...
  Found 12 packages with newer versions available

Step 3/5: Resolving dependency constraints...
  3 packages can be safely upgraded

Step 4/5: Packages ready for upgrade:

┏━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
┃ Package       ┃ Current ┃ Latest  ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
│ requests      │ 2.28.0  │ 2.31.0  │
│ rich          │ 13.0.0  │ 13.7.0  │
│ click         │ 8.1.3   │ 8.1.7   │
└───────────────┴─────────┴─────────┘

Do you want to proceed with the upgrade? [Y/n]: y

Step 5/5: Upgrading packages...
Successfully installed requests-2.31.0 rich-13.7.0 click-8.1.7

Successfully upgraded 3 package(s)
  - requests: 2.28.0 -> 2.31.0
  - rich: 13.0.0 -> 13.7.0
  - click: 8.1.3 -> 8.1.7

Usage Examples

Install packages

# Install packages (installs or updates to latest by default)
pipu install requests flask numpy

# Install without updating existing packages
pipu install requests --no-update

# Install with version constraints
pipu install "requests>=2.30" "flask==2.3.0"

# Install across a group of environments
pipu install requests -g data-science

# Include pre-release versions
pipu install requests --pre

Upgrade specific packages only

# Upgrade a single package
pipu upgrade requests

# Upgrade multiple specific packages
pipu upgrade requests numpy pandas

Upgrade to a specific version

# Pin to exact version
pipu upgrade requests==2.31.0

# Use version constraints
pipu upgrade "requests>=2.30,<3.0"

Check for outdated packages

pipu outdated

Shows all packages that have updates available without installing anything.

Exclude packages from upgrade

# Exclude single package
pipu upgrade --exclude numpy
pipu upgrade -e numpy

# Exclude multiple packages (repeatable flag)
pipu upgrade -e numpy -e pandas -e scipy

See why packages can't be upgraded

pipu upgrade --show-blocked
pipu upgrade -b

This displays packages that have updates available but can't be upgraded due to dependency constraints, along with the specific constraints blocking them.

Skip confirmation prompt (for scripts/automation)

pipu -y

Machine-readable JSON output

pipu outdated --output json
pipu upgrade --output json
pipu upgrade -o json

Useful for CI/CD pipelines and scripting.

Speed up version checking with parallel requests

pipu upgrade --parallel 10

Uses multiple concurrent requests to check for updates (default: min(4, CPU count)).

Update requirements.txt after upgrade

pipu upgrade --update-requirements requirements.txt

Automatically updates your requirements file with the new versions after a successful upgrade.

Include pre-release versions

pipu upgrade --pre

Debug mode

pipu upgrade --debug

Shows timing information and explains why packages can or cannot be upgraded.

Rollback

If an upgrade causes problems, you can rollback to the previous state:

# Preview what would be rolled back
pipu rollback --dry-run

# Perform the rollback
pipu rollback

# List all saved states
pipu rollback --list

# Rollback to a specific state
pipu rollback --state state_20241205_143022.json

pipu automatically saves your package state before each upgrade, so you can always revert if needed.

Caching

pipu caches package version information to speed up repeated runs. The cache is per-environment, so it works correctly with venv, conda, mise, and other environment managers.

# Refresh the cache manually
pipu update

# Upgrade using cached data (default behavior)
pipu upgrade

# Force fresh version check, ignoring cache
pipu upgrade --no-cache

# Clear cache for current environment
pipu clean

# Clear all caches
pipu clean --all

By default, the cache is considered fresh for 1 hour. You can adjust this:

# Use a shorter TTL (in seconds)
pipu upgrade --cache-ttl 300

Environment Groups

If you manage multiple Python environments (e.g., separate conda envs for data science, web development, tooling), groups let you operate on all of them with a single command.

Managing groups

# Add the current Python environment to a group
pipu group add data-science

# Add a specific environment
pipu group add data-science --python /path/to/envs/ml/bin/python

# List all groups
pipu group list

# Remove an environment from a group
pipu group remove data-science --python /path/to/envs/ml/bin/python

# Delete an entire group
pipu group delete data-science

Running commands across groups

# Check for outdated packages in all environments
pipu outdated -g data-science

# Upgrade all environments in a group
pipu upgrade -g data-science

# Upgrade with auto-confirm
pipu upgrade -g data-science --yes

When using -g, pipu runs the command for each environment sequentially. All standard flags (--exclude, --pre, --timeout, etc.) apply uniformly to every environment.

Groups are stored at ~/.config/pipu/groups.toml and work across projects.

Command Reference

Commands

Command	Description
pipu install	Install packages (wraps pip install -U)
pipu upgrade	Upgrade packages (default command)
pipu outdated	Show packages with updates available
pipu update	Refresh the package version cache
pipu clean	Clear caches
pipu rollback	Restore packages to a previous state
pipu group list	List all environment groups
pipu group add	Add an environment to a group
pipu group remove	Remove an environment from a group
pipu group delete	Delete an entire group

Upgrade Options

Option	Short	Description
PACKAGES		Optional package names to upgrade (default: all)
--exclude TEXT	-e	Package to exclude (repeatable)
--show-blocked	-b	Show packages blocked by constraints
--group TEXT	-g	Run across all environments in a named group
--output [human|json]	-o	Output format (default: human)
--parallel INTEGER	-p	Number of parallel version check requests (default: min(4, CPU count))
--update-requirements PATH		Update a requirements.txt file after upgrade
--no-cache		Skip cache and fetch fresh version data
--cache-ttl INTEGER		Cache freshness threshold in seconds (default: 3600)
--timeout INTEGER		Network timeout in seconds (default: 10)
--pre		Include pre-release versions
--yes	-y	Skip confirmation prompt
--debug		Show detailed logging and timing info

Install Options

Option	Short	Description
PACKAGES		Package names to install (required)
--no-update		Use plain pip install without -U flag
--group TEXT	-g	Install across all environments in a named group
--output [human|json]	-o	Output format (default: human)
--timeout INTEGER		Installation timeout in seconds (default: 300)
--pre		Include pre-release versions
--yes	-y	Skip confirmation prompt
--debug		Show detailed logging and timing info

Rollback Options

Option	Short	Description
--list	-l	List all saved rollback states
--dry-run		Show what would be rolled back
--state FILE		Rollback to a specific state file
--yes	-y	Skip confirmation prompt

Clean Options

Option	Short	Description
--all	-a	Clear cache for all environments

Group Add Options

Option	Short	Description
GROUP_NAME		Name of the group (required)
--python PATH		Path to Python interpreter (default: current Python)
--force	-f	Skip Python path validation

Configuration File

pipu supports configuration files to set default options. Create a .pipu.toml file in your project directory:

timeout = 30
exclude = ["numpy", "pandas"]
pre = false
parallel = 5
cache_ttl = 3600
cache_enabled = true

Or add a [tool.pipu] section to your pyproject.toml:

[tool.pipu]
timeout = 30
exclude = ["numpy", "pandas"]
parallel = 5

You can also create a user-level config at ~/.config/pipu/config.toml.

Priority: Command-line options > Project config > User config

Environment Variables

Variable	Description
PIPU_TIMEOUT	Network timeout in seconds (default: 10)
PIPU_CACHE_TTL	Cache freshness threshold in seconds (default: 3600)
PIPU_CACHE_ENABLED	Enable/disable caching (default: true)
PIPU_CACHE_DIR	Cache directory (default: ~/.pipu/cache)

How Does It Work?

pipu analyzes your package dependencies to determine which packages can be upgraded without breaking anything:

• Safe by default: Only upgrades packages when all dependency constraints are satisfied
• Batch upgrades: Upgrades compatible packages together, letting pip's resolver handle the details
• Smart resolution: Uses a fixed-point iteration algorithm to handle complex dependency scenarios, including circular dependencies
• Rollback support: Saves package state before upgrades so you can revert if needed
• Per-environment caching: Caches version data separately for each Python environment (venv, conda, mise, etc.)

If pipu says a package can't be upgraded, it's usually because upgrading it would break another package. Use --show-blocked to see exactly which constraints are preventing the upgrade.

Common Questions

Q: Is it safe to use pipu? A: Yes! pipu only upgrades packages when it's safe to do so. It uses the same pip underneath, with added safety checks. Plus, you can always rollback if needed.

Q: Why didn't pipu upgrade package X? A: Probably because upgrading it would break another package. Use --show-blocked to see the specific constraints, or --debug for more details.

Q: Can I use pipu in scripts or CI/CD? A: Absolutely! Use pipu --yes --output json for automated workflows.

Q: What if all my packages are blocked? A: This means upgrading them would cause conflicts. This is actually good - pipu is preventing a broken environment.

Q: Does pipu work with private PyPI repositories? A: Yes! pipu respects your pip configuration (index-url, extra-index-url, trusted-host, etc.).

Q: How do I speed up pipu for large environments? A: Use --parallel 10 (or higher) to check multiple packages concurrently.

Tips

• Run pipu regularly to keep your packages up-to-date
• Use pipu outdated first to preview what can be upgraded
• Use --show-blocked to understand why certain packages can't be upgraded
• Use --update-requirements to keep your requirements.txt in sync
• Use pipu update to refresh the cache before checking for updates
• Use virtual environments to isolate different projects
• Use pipu group to manage multiple environments and upgrade them all at once

Troubleshooting

"No packages can be upgraded (all blocked by constraints)"

This means all available updates would violate dependency constraints. Your environment is in a stable state, which is good! If you really need a specific update:

1. Use --show-blocked to see what's blocking each package
2. Consider upgrading the blocking packages first
3. Or manually upgrade with pip install --upgrade package-name if you accept the risk

Network timeout errors

If you see timeout errors, increase the timeout:

pipu --timeout 30

Stale cache data

If pipu shows outdated version info, refresh the cache:

pipu update
# or
pipu upgrade --no-cache

Rolling back after a bad upgrade

If something broke after an upgrade:

pipu rollback

Requirements

• Python 3.10 or higher
• pip (comes with Python)

License

MIT License - See LICENSE file for details

Author

Scott Arne Johnson ([e-mail])

Contributing

Found a bug or want to contribute? Check out the GitHub repository!