Installation Guide

📦 Installation Guide

This page explains how to install ExifPlus across common environments (pip, pipx, virtualenv), and covers platform-specific notes for Windows, macOS, Linux (Debian/Ubuntu/Raspbian/Parrot/Kali).

---

Requirements

• Python 3.9 or newer
• Optional native libs (for full functionality):
  • libexiv2 (system library used by pyexiv2)
  • tkinter (GUI; usually bundled with Python)
• Python packages (installed via pip/pipx):
  • pyexiv2, hachoir, ttkbootstrap, exifread, Pillow

---

1) Recommended: Install with pipx (isolation + CLI)

pipx install exifplus

Then run:

exifplus

---

2) Install inside a virtual environment (recommended for Debian-based distros)

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install exifplus

---

3) System-wide pip (not recommended on Debian/Ubuntu/Parrot/Kali due to PEP 668)

You may encounter:

error: externally-managed-environment

Fix: use pipx or create a virtual environment instead.

If you must force-install (not recommended):

pip install exifplus --break-system-packages

---

4) Installing native dependencies (pyexiv2) — Linux

pyexiv2 depends on the exiv2 system library. On Debian/Ubuntu/Parrot/Kali:

sudo apt update
sudo apt install libexiv2-dev libexiv2-27
# Then
pip install pyexiv2

On some systems you may need to build from source or use distro packages.

---

5) macOS

Install exiv2 via Homebrew:

brew install exiv2
pip install pyexiv2
pip install exifplus

If you face compilation issues, ensure Xcode command-line tools are installed:

xcode-select --install

---

6) Windows

Windows users may face trouble installing pyexiv2 because the native binary wheels may not be available or the underlying library is missing.

Options:

• Use the virtualenv and pip install prebuilt wheels (if available).
• Use the packaged EXE (if you build one), or run the app from WSL (Windows Subsystem for Linux).
• For full editing support, prefer Linux/macOS.

---

7) Confirm installation

# If installed with pipx:
exifplus --help

# Or:
python -m exifplus

---

8) Troubleshooting installation

• If pyexiv2 fails to install: install exiv2 system library first (see above).
• If GUI fails: ensure tkinter is installed (sudo apt install python3-tk on Debian-based OS).
• If you see PEP 668 errors: use pipx or virtualenv.

---

9) Uninstall

pip uninstall exifplus
# or pipx uninstall exifplus

---

10) Additional notes

• For CI/builds and ReadTheDocs, pyexiv2 can be mocked in Sphinx to allow docs to build without native libs.
• Keep backups of files before using Save/Write metadata features.