Installation

Requirements

GUI Image Studio requires Python 3.8 or later and works with the following operating systems:

  • Windows 10/11

  • macOS 10.14+

  • Linux (Ubuntu 18.04+, CentOS 7+, or equivalent)

Dependencies

The package has the following dependencies:

  • tkinter - Usually included with Python

  • customtkinter - Modern UI components

  • Pillow (PIL) - Image processing library

  • typing-extensions - For Python < 3.10 compatibility

Install from PyPI

The easiest way to install GUI Image Studio is using pip:

pip install gui-image-studio

This will install the latest stable version from PyPI along with all required dependencies.

Install from Source

To install the latest development version from GitHub:

pip install git+https://github.com/stntg/gui-image-studio.git

Development Installation

If you want to contribute to GUI Image Studio or modify the source code:

git clone https://github.com/stntg/gui-image-studio.git
cd gui-image-studio
pip install -e .[dev]

This installs the package in “editable” mode with development dependencies including:

  • pytest - Testing framework

  • black - Code formatting

  • flake8 - Code linting

  • mypy - Type checking

  • sphinx - Documentation generation

Verify Installation

To verify that GUI Image Studio is installed correctly:

import gui_image_studio
print(gui_image_studio.__version__)

Or test the CLI commands:

gui-image-studio-designer --version
gui-image-studio-create-samples --help

Or run the verification script:

python scripts/verify-install.py

Troubleshooting

Common Issues

ImportError: No module named ‘tkinter’

On some Linux distributions, tkinter is not installed by default:

# Ubuntu/Debian
sudo apt-get install python3-tk

# CentOS/RHEL/Fedora
sudo yum install tkinter
# or
sudo dnf install python3-tkinter

ImportError: No module named ‘customtkinter’

If CustomTkinter is not installed automatically:

pip install customtkinter

PIL/Pillow Issues

If you encounter Pillow-related errors:

pip install --upgrade Pillow

Display Issues on Linux

If you’re running on a headless Linux server or in a container, you may need to set up a virtual display:

sudo apt-get install xvfb
export DISPLAY=:99
Xvfb :99 -screen 0 1024x768x24 &

Permission Issues

If you encounter permission errors during installation:

pip install --user gui-image-studio

This installs the package for the current user only.

Windows-Specific Issues

On Windows, if you encounter issues with the GUI not displaying properly:

  1. Ensure you have the latest Windows updates

  2. Try running as administrator

  3. Check Windows Defender/antivirus settings

macOS-Specific Issues

On macOS, if you encounter permission issues:

# Use Homebrew Python instead of system Python
brew install python
/usr/local/bin/pip3 install gui-image-studio

Optional Dependencies

For enhanced functionality, you can install optional dependencies:

Enhanced Image Formats

pip install pillow-heif  # HEIF/HEIC support
pip install pillow-avif  # AVIF support

Performance Improvements

pip install numpy  # Faster array operations
pip install opencv-python  # Advanced image processing

Development Tools

pip install gui-image-studio[dev]  # All development dependencies

Getting Help

If you encounter issues not covered here:

  1. Check the GitHub Issues

  2. Search the documentation

  3. Run the diagnostic script: python scripts/verify-install.py

  4. Create a new issue with details about your environment and the problem

System Requirements

Minimum Requirements

  • Python 3.8+

  • 512 MB RAM

  • 100 MB disk space

  • Display resolution: 1024x768

Recommended Requirements

  • Python 3.10+

  • 2 GB RAM

  • 500 MB disk space

  • Display resolution: 1920x1080 or higher

  • Dedicated graphics card (for better performance with large images)

Supported Image Formats

  • Input: PNG, JPEG, GIF, BMP, TIFF, WebP, ICO

  • Output: PNG, JPEG, GIF, BMP, TIFF, WebP

  • Animation: GIF (with timeline editing support)