Skip to content

Installation

This guide will help you install Image Namer on your system.

Choose Your Installation

Image Namer offers two interfaces:

  • CLI only (lightweight): ~50MB with dependencies
  • CLI + GUI (full experience): ~150MB including Qt6 libraries

pipx is the recommended installation method for Image Namer. It installs Python CLI tools in isolated environments, preventing dependency conflicts with other Python projects on your system.

1. Install pipx

If you don't already have pipx:

brew install pipx
pipx ensurepath

python3 -m pip install --user pipx
python3 -m pipx ensurepath

python -m pip install --user pipx
python -m pipx ensurepath

After installation, restart your terminal to ensure the PATH is updated.

2. Install Image Namer

CLI Only (lightweight): 

pipx install image-namer

CLI + GUI (recommended): 

pipx install 'image-namer[gui]'

The [gui] extra installs PySide6 (Qt6 for Python), which adds the graphical interface.

3. Verify Installation

CLI: 

image-namer --help

GUI (if installed with [gui]): 

image-namer-ui

Alternative: pip Installation

Not Recommended

Installing with pip can cause dependency conflicts with other Python projects. Use pipx unless you have a specific reason not to.

CLI only: 

pip install image-namer

CLI + GUI: 

pip install 'image-namer[gui]'

Development Installation

If you're contributing to Image Namer or want to modify the code:

1. Clone the Repository

git clone https://github.com/svetzal/image-namer.git
cd image-namer

2. Install with Development Dependencies

Using uv (recommended for development):

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install with GUI for testing
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev,gui]"

Using pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev,gui]"

The [dev] extra includes testing tools (pytest, flake8, mypy) and documentation tools (mkdocs). The [gui] extra includes PySide6 for the graphical interface.

System Requirements

  • Python 3.13 or later
  • AI Provider: You'll need either:
    • Ollama (recommended): Local, privacy-friendly, free
    • OpenAI API: Cloud-based, requires API key and costs money

Ollama runs AI models locally on your machine:

  1. Download from ollama.com
  2. Install the application
  3. Pull the default model: 
    ollama pull gemma3:27b

Ollama runs as a background service and provides a local API endpoint.

Setting up OpenAI

If you prefer OpenAI:

  1. Get an API key from platform.openai.com
  2. Set the environment variable: 
    export OPENAI_API_KEY='your-api-key-here'

Add this to your ~/.zshrc, ~/.bashrc, or equivalent shell config for persistence.

Upgrading

pipx Installation

pipx upgrade image-namer

pip Installation

pip install --upgrade git+https://github.com/svetzal/image-namer.git

Development Installation

cd image-namer
git pull
uv pip install -e ".[dev,gui]"  # or: pip install -e ".[dev,gui]"

Uninstalling

pipx Installation

pipx uninstall image-namer

pip Installation

pip uninstall image-namer

Next Steps