moma/INSTALL.md

Installation Guide for moma

moma is a terminal-based media file renamer and metadata viewer built with Python and Textual.

Prerequisites

• Python 3.12 or higher
• UV package manager (recommended) or pip

Installation Methods

Method 1: UV Tool Install (Recommended)

This is the easiest way to install and use moma globally on your system.

Install UV (if not already installed)

# On Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.sh | iex"

Install moma

# Always-latest (recommended, no version to update)
uv tool install https://github.com/shadoll/moma/releases/latest/download/moma-latest.tar.gz

# Specific version
uv tool install https://github.com/shadoll/moma/releases/download/v0.9.6/moma-0.9.6-py3-none-any.whl

# From PyPI (when published)
uv tool install moma

Reinstall / Upgrade moma

# Reinstall (same URL — force overwrite)
uv tool install --force https://github.com/shadoll/moma/releases/latest/download/moma-latest.tar.gz

# Upgrade to a newer specific version
uv tool install --force https://github.com/shadoll/moma/releases/download/v0.9.6/moma-0.9.6-py3-none-any.whl

Usage

moma                    # Scan current directory
moma /path/to/directory # Scan specific directory

Method 2: pip Install from Wheel

# Always-latest (recommended, no version to update)
pip install https://github.com/shadoll/moma/releases/latest/download/moma-latest.tar.gz

# Specific version
pip install https://github.com/shadoll/moma/releases/download/v0.9.6/moma-0.9.6-py3-none-any.whl

Method 3: Development Installation

For development or if you want to run from source:

Clone and Setup

git clone git@github.com:shadoll/moma.git
cd moma

# Install dependencies
uv sync

# Run directly
uv run python src/main.py
uv run python src/main.py /path/to/directory

Install in Development Mode

uv sync
uv tool install --editable .

Method 4: Direct Python Execution

If you prefer not to install globally:

# Ensure you have Python 3.12+
python3 --version

# Install dependencies
pip install textual mutagen pymediainfo python-magic langcodes

# Run the application
python3 src/main.py
python3 src/main.py /path/to/directory

System Requirements

Linux

• Python 3.12+
• MediaInfo library (for detailed media analysis)

  # Ubuntu/Debian
  sudo apt install libmediainfo-dev
  
  # Fedora/CentOS
  sudo dnf install libmediainfo-devel
  
  # Arch Linux
  sudo pacman -S libmediainfo
  

macOS

• Python 3.12+ (via Homebrew or official installer)
• MediaInfo (automatically handled by pymediainfo)

Windows

• Python 3.12+ (official installer)
• MediaInfo (automatically handled by pymediainfo)

Downloading Releases

All release packages (.whl and .tar.gz) are attached to each GitHub Release. Releases are built automatically by CI when a version tag (v*.*.*) is pushed.

---

Verification

After installation, verify it works:

moma --help

You should see the help text for the moma application.

Troubleshooting

Common Issues

1. "Command not found"

   • Ensure UV bin directory is in your PATH
   • Try uv tool install again

2. Import errors

   • Ensure all dependencies are installed
   • Try uv sync or pip install -r requirements.txt

3. Permission errors

   • Use sudo for system-wide pip installs
   • Or use UV tool install which handles permissions

4. MediaInfo not found

   • Install system MediaInfo library
   • Or use basic mode (limited functionality)

Getting Help

If you encounter issues:

1. Check the README.md for usage instructions
2. Verify your Python version: python3 --version
3. Check UV installation: uv --version

Uninstallation

UV Tool Uninstall

uv tool uninstall moma

pip Uninstall

pip uninstall moma

Development Uninstall

uv tool uninstall moma
# Remove the cloned directory if desired
```</content>
<parameter name="filePath">/Users/sha/Developer/sha.dev/moma/INSTALL.md