Installation

This guide walks you through installing AI Image Renamer CLI on your system. Choose the method that best fits your workflow.

Prerequisites

Before installing, make sure you have:

• Python 3.8+ installed
• pip (Python's package manager)
• A Groq API key set in your environment

Installation Methods

Method 1: pip Install (Recommended)

The simplest way to install the tool globally:

pip install ai-image-renamer

This installs the rename-images command system-wide.

Upgrading

To update to the latest version:

pip install --upgrade ai-image-renamer

Method 2: pipx Install

pipx installs Python CLI tools in isolated environments, preventing dependency conflicts:

# Install pipx if you don't have it
pip install pipx
pipx ensurepath

# Install the tool
pipx install ai-image-renamer

Why pipx?

pipx combines the simplicity of global installation with the isolation of virtual environments. Each tool runs in its own environment, avoiding conflicts with other packages.

To upgrade:

pipx upgrade ai-image-renamer

To uninstall:

pipx uninstall ai-image-renamer

Method 3: Virtual Environment

Using a virtual environment keeps dependencies isolated from other projects:

# Create a new directory for your project
mkdir my-photos && cd my-photos

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate  # macOS/Linux
# or
.\venv\Scripts\activate   # Windows

# Install the tool
pip install ai-image-renamer

The rename-images command is now available only when the virtual environment is active.

Why Use Virtual Environments?

Virtual environments prevent dependency conflicts between projects. If Project A needs library==1.0 and Project B needs library==2.0, virtual environments let both coexist.

Method 4: User Installation

Install to your user directory (doesn't require admin privileges):

pip install --user ai-image-renamer

This installs to ~/.local/bin/ on Linux/macOS or %APPDATA%\Python\Scripts\ on Windows.

PATH Configuration

If the command isn't found after user installation, add the scripts directory to your PATH:

Linux/macOS (add to ~/.bashrc or ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

Windows (PowerShell as Administrator):

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:APPDATA\Python\Scripts", "User")

Method 5: Install from Source

For development or if you want the latest unreleased changes:

# Clone the repository
git clone https://gitlab.com/thaikolja/ai-image-renamer-cli.git
cd ai-image-renamer-cli

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in editable mode
pip install -e .

The -e flag creates an "editable" installation — changes to the source code take effect immediately without reinstalling.

Verifying Installation

Confirm the installation was successful:

rename-images --version

Expected output:

rename-images 1.1.0

If you see "command not found", see the Troubleshooting section below.

Setting Up Your API Key

The tool requires a Groq API key. Set it as an environment variable:

Option A: Shell Configuration (Persistent)

Add to your shell configuration file:

Bash (~/.bashrc):

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

Zsh (~/.zshrc):

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

Option B: .env File (Per-Project)

Create a .env file in your working directory:

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

The tool automatically loads .env files in the current directory.

Security

Add .env to your .gitignore to avoid accidentally committing your API key:

echo ".env" >> .gitignore

Option C: One-Time Export (Temporary)

For a single session:

export GROQ_API_KEY="gsk_your-key-here"

This lasts until you close your terminal.

Quick Test

Run a quick test to verify everything works:

# Create a test image or use an existing one
rename-images path/to/any-image.jpg

Expected output:

Processing path/to/any-image.jpg...
Renamed path/to/any-image.jpg to /path/to/descriptive-filename.jpg

Uninstallation

To remove the tool:

pip uninstall ai-image-renamer

If installed in a virtual environment, deactivate it first:

deactivate
pip uninstall ai-image-renamer

Troubleshooting

"command not found: rename-images"

Cause: The installation directory isn't in your PATH.

Solution:

1. Find where pip installed the command:

   pip show ai-image-renamer

2. Look for the Location field
3. Add the bin subdirectory to your PATH

"Permission denied"

Cause: Installing to system directories without proper permissions.

Solution: Use the --user flag:

pip install --user ai-image-renamer

"Requirement already satisfied"

Cause: The package is already installed.

Solution: To reinstall or upgrade:

pip install --upgrade --force-reinstall ai-image-renamer

"GROQ_API_KEY not set"

Cause: The environment variable isn't configured.

Solution: See Setting Up Your API Key above.

Next Steps

• Quick Start Guide — Rename your first image
• Command Options — Learn all available options
• Environment Variables — Configure the tool