Requirements

Before installing AI Image Renamer CLI, make sure your system meets these requirements. The tool is designed to work on most modern systems with minimal setup.

System Requirements

Operating System

The tool works on all major operating systems:

OS	Support	Notes
macOS	✅ Full support	Tested on macOS 12+
Linux	✅ Full support	Tested on Ubuntu, Debian, Fedora
Windows	✅ Full support	Use WSL or PowerShell

Python Version

You need Python 3.8 or higher.

Checking Your Python Version

Run this command in your terminal:

python3 --version

Output should show Python 3.8.x or higher. If you see Python 2.x, try python --version instead.

If you don't have Python installed or need a newer version:

• macOS: brew install python or download from python.org
• Linux: Use your package manager (apt install python3, yum install python3, etc.)
• Windows: Download from python.org or use Microsoft Store

API Requirements

Groq API Key

You need a Groq API key to use the AI features. Groq provides a generous free tier that's perfect for this tool.

Getting Your Free API Key

1. Go to console.groq.com
2. Sign up (no credit card required)
3. Navigate to API Keys in the sidebar
4. Click Create API Key
5. Copy your key (starts with gsk_)

Keep Your Key Secret

Your API key is like a password. Never share it publicly or commit it to version control.

Setting Up Your Key

Add your API key to your shell configuration:

For Bash users (~/.bashrc):

echo 'export GROQ_API_KEY="gsk_your-key-here"' >> ~/.bashrc
source ~/.bashrc

For Zsh users (~/.zshrc or ~/.zprofile):

echo 'export GROQ_API_KEY="gsk_your-key-here"' >> ~/.zshrc
source ~/.zshrc

Alternative: Using a .env file

Create a .env file in your working directory:

echo 'GROQ_API_KEY="gsk_your-key-here"' > .env

The tool automatically loads .env files using python-dotenv.

Groq Free Tier Limits

The free tier includes:

Resource	Limit
Requests per minute	30
Tokens per minute	7,000
Requests per day	14,400

For most users, these limits are more than sufficient. Processing 100 images uses approximately 100 API calls.

What Are Tokens?

Tokens are pieces of text that AI models process. A token is roughly 4 characters or 0.75 words in English. Image descriptions typically use 20-50 tokens each.

Package Dependencies

The tool automatically installs these Python packages:

Package	Purpose
groq	Official Groq API client
filetype	File type detection via magic bytes
python-dotenv	Environment variable loading from .env

You don't need to install these manually — pip handles them automatically.

Recommended Tools

pip Package Manager

pip is Python's package manager. It comes installed with Python.

Upgrading pip

It's good practice to use the latest pip:

pip install --upgrade pip

Virtual Environment (Recommended)

A virtual environment creates an isolated Python installation, preventing conflicts with other projects.

# Create a virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate  # macOS/Linux
# or
.\venv\Scripts\activate   # Windows

# Install the tool
pip install ai-image-renamer

System-Wide Installation (Alternative)

If you want rename-images available everywhere without activating a virtual environment:

pip install --user ai-image-renamer

The --user flag installs to your home directory, avoiding system-wide changes.

Disk Space

The tool itself is small (under 1 MB). However, consider:

• Python installation: ~100-200 MB
• Dependencies: ~10-20 MB
• Virtual environments: ~50-100 MB each (if used)

Network Requirements

The tool requires internet access to communicate with Groq's API servers.

Requirement	Details
Connection	HTTPS (port 443)
Endpoint	https://api.groq.com/
Latency	Typically 100-500ms per request
Bandwidth	Minimal (images compressed to Base64)

Quick Checklist

Before proceeding to installation, verify:

• [ ] Python 3.8+ installed (python3 --version)
• [ ] pip available (pip --version)
• [ ] Groq API key obtained from console.groq.com
• [ ] API key set in environment (echo $GROQ_API_KEY)
• [ ] Internet connection available

Troubleshooting

"Python command not found"

Your Python installation might use a different command:

python --version    # Try without the '3'
py --version        # Windows
python3.11 --version  # Specific version

"pip command not found"

Try:

python3 -m pip --version
python -m pip --version

"GROQ_API_KEY not set"

Verify your environment variable:

echo $GROQ_API_KEY  # macOS/Linux
echo %GROQ_API_KEY%  # Windows CMD
$env:GROQ_API_KEY    # Windows PowerShell

If empty, re-add it to your shell config and reload.

Next Steps

Ready to install? Head to the Installation Guide.