Skip to content

Installation Guide

curl -sSL https://shotx.vedeshpadal.me/install.sh | sh

This automatically:

  1. Detects your package manager (apt / dnf / pacman / zypper / apk)
  2. Installs all system dependencies
  3. Installs uv if not present
  4. Clones ShotX to ~/.local/share/shotx/
  5. Creates a shotx launcher at ~/.local/bin/shotx
  6. Adds an XDG autostart entry so ShotX launches on login

Note

~/.local/bin must be in your PATH. If it isn't, add this to your shell config and restart:

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

Env-var overrides for CI / Docker builds:

# Skip system dep installation (if you manage deps yourself)
SKIP_SYSTEM_DEPS=1 sh install.sh

# Skip XDG autostart entry creation
SKIP_AUTOSTART=1 sh install.sh

Native Packages

Download the latest .deb, .rpm, or AppImage from the GitHub Releases page.

# Ubuntu / Debian
sudo dpkg -i shotx_*.deb

# Fedora / RHEL
sudo rpm -i shotx-*.rpm

# AppImage (any distro)
chmod +x ShotX-*.AppImage && ./ShotX-*.AppImage

The .deb and .rpm packages bundle a private Python runtime — no system Python or library conflicts.

Homebrew (Linux)

brew tap vedesh-padal/tap
brew install shotx

Note

After install, run shotx to start. The Welcome dialog will guide you through desktop integration on first launch.

From Source (Manual)

Prerequisites

  • Python 3.10 or later
  • uv (recommended) or pip
  • A Linux desktop with Wayland or X11

Steps

# Clone the repository
git clone https://github.com/vedesh-padal/ShotX.git
cd ShotX

# Set up with uv
uv sync --all-groups

# Launch
uv run shotx           # System tray mode
uv run shotx --help    # See all CLI options

Tip

You can also use the inclusive Justfile or Makefile in the root for automated setup and development tasks (e.g., just setup-deps-debian, just sync).

With pip

git clone https://github.com/vedesh-padal/ShotX.git
cd ShotX
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[all,dev]"
shotx

System Dependencies

Some features require system packages. ShotX works without them but with reduced functionality.

Required

Package Purpose Install
Python 3.10+ Runtime Pre-installed on most distros
Package Purpose Install (Ubuntu/Debian)
xclip Persistent clipboard in X11 CLI mode sudo apt install xclip
wl-copy Persistent clipboard in Wayland CLI mode sudo apt install wl-clipboard

Optional (Feature-Specific)

Package Feature Install (Ubuntu/Debian)
tesseract-ocr OCR text extraction sudo apt install tesseract-ocr
libzbar0 QR code scanning sudo apt install libzbar0
ffmpeg Screen recording (X11), GIF conversion sudo apt install ffmpeg
wf-recorder Screen recording (Wayland/wlroots) sudo apt install wf-recorder
grim Screenshots on Sway/Hyprland sudo apt install grim
slurp Region selection on Sway/Hyprland sudo apt install slurp

Note

PyGObject is automatically downloaded as a core Python dependency for native DBus notifications. However, if you are building from source, you may need to install the system headers. The exact package name depends on your Ubuntu/Debian version:

  • Ubuntu 22.04 / Debian 11: sudo apt install libcairo2-dev libgirepository1.0-dev pkg-config
  • Ubuntu 24.04+ / Debian 12+: sudo apt install libcairo2-dev libgirepository-2.0-dev pkg-config

PyPI (Coming Soon)

ShotX is not yet published to PyPI. Install from source (above) or watch the releases page.