Skip to content

Quick Start Guide#

Get up and running with ISCC-SUM in minutes! This guide shows you how to install and use the command-line tool to generate similarity-preserving ISCC checksums for files and directories.

New to Terminal/Command Line? Start Here!

If you've never used a terminal (also called command line) before, don't worry! Here's a quick primer:

What is a Terminal?

A terminal is a text-based way to interact with your computer. Instead of clicking buttons, you type commands.

How to Open a Terminal:

  • Press Win+R, type cmd or powershell, and press Enter
  • Or: Right-click the Start button and select "Windows Terminal" or "Command Prompt"
  • Press Cmd+Space, type terminal, and press Enter
  • Or: Go to Applications → Utilities → Terminal
  • Press Ctrl+Alt+T
  • Or: Look for "Terminal" in your applications menu

Basic Terminal Commands You'll Need:

  • cd foldername - Navigate into a folder (cd = "change directory")
  • cd .. - Go back to the parent folder
  • ls (macOS/Linux) or dir (Windows) - List files in current folder
  • pwd - Show current folder path (print working directory)

Example Navigation:

# See where you are
pwd

# List files in current folder
ls                    # macOS/Linux
dir                   # Windows

# Navigate to your Documents folder
cd Documents

# Go back one level
cd ..

Tips for Beginners:

  • 💡 Commands are case-sensitive on macOS/Linux
  • 💡 Press Tab to auto-complete file/folder names
  • 💡 Press Up to recall previous commands
  • 💡 Type clear (macOS/Linux) or cls (Windows) to clear the screen
  • 💡 Copy text: Ctrl+C (Windows/Linux) or Cmd+C (macOS)
  • 💡 Paste text: Ctrl+V (Windows/Linux) or Cmd+V (macOS)

🚀 Installation in 10 Seconds#

The fastest way to use ISCC-SUM is with UV:

Step 1: Install UV (One-time Setup)#

UV is a modern Python tool installer that handles everything for you - including Python itself!

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After Installation

Close and reopen your terminal to ensure UV is available in your PATH.

Step 2: Run ISCC-SUM Instantly#

Now you can run ISCC-SUM without any further installation. Let's try it with a test file:

# Create a test file
echo "Hello ISCC!" > test.txt

# Generate its ISCC checksum
uvx iscc-sum test.txt

You should see output like this:

ISCC:K4AND37MEJ2QHCZ2DK5OUWSF7FGIYKDWBBPG3VOKM6FE5NPXZXA33SI *test.txt

It worked!

Congratulations! You just generated your first ISCC checksum. The long string starting with "ISCC:" is a unique fingerprint of your file's content.

Using with your own files

To process your own files, simply navigate to their location first:

# Navigate to the folder with your files
cd Documents

# Run ISCC-SUM on any file
uvx iscc-sum myfile.pdf

📦 Permanent Installation#

For frequent use, install ISCC-SUM globally:

uv tool install iscc-sum

After installation, you can simply type iscc-sum from anywhere in your terminal.

✨ Basic Examples#

What's an ISCC Checksum?

Think of it like a unique ID for your file's content. If the file changes even slightly, the fingerprint changes too. This helps you:

  • 🔍 Detect if files have been modified
  • ♊ Find duplicate or similar files
  • 🛡 Verify file integrity

Generate a checksum for a single file#

Open your terminal in the folder containing your file, then run:

iscc-sum document.pdf

Output:

ISCC:KAATT7GQ6V5CDXEHRJPQBU3YH7V2XMCSADJWV3CZQFOPH5LOGZQQ  document.pdf

The long string starting with "ISCC:" is your file's unique fingerprint.

Process multiple files#

To process all JPEG images in a folder:

iscc-sum *.jpg

Output:

ISCC:KAAUSPE5KJYTY43L5OR4A5YLKQVVIMRYVFVJDVCZV5YKOEAPH3JA  image1.jpg
ISCC:KAAQZVGNJY4D2IFXEWV6DZF5JMHZ2C2ZXSOD5RCQGQEMAVVZ5VIA  image2.jpg
ISCC:KAASFWXNH6S3S7OLJQMGOQNLSCZ74CTQV3SJVHGJJ76SUXKGDZXQ  image3.jpg

Wildcard Patterns

The * symbol means "all files". So *.jpg means "all files ending with .jpg"

Verify file integrity#

This is useful for checking if your files have been modified or corrupted.

Step 1: Save checksums to a file

iscc-sum *.txt -o checksums.iscc

This creates a file called checksums.iscc containing fingerprints of all .txt files.

Cross-platform Compatibility

The -o option ensures cross-platform compatible output (UTF-8, LF line endings), avoiding issues with shell redirection on Windows.

Step 2: Later, verify the files haven't changed

iscc-sum --check checksums.iscc

Output:

file1.txt: OK
file2.txt: OK
file3.txt: FAILED
iscc-sum: WARNING: 1 computed checksum did NOT match

This tells you that file3.txt has been modified since you created the checksums.

📁 Tree Mode - Process Entire Directories#

Sometimes you want a single fingerprint for an entire folder and all its contents. This is called "tree mode".

iscc-sum --tree ./my-subfolder

What Tree Mode Captures

This creates one unique fingerprint that represents:

  • 📄 All files in the folder
  • 📁 All subfolders and their files
  • 🏗 The folder structure itself

When to use tree mode

  • 📷 Creating a "snapshot" of a project folder
  • 🔍 Checking if anything in a folder has changed
  • 📦 Archiving or backing up folder structures

⚖ Comparison with Familiar Tools#

If you've used md5sum or sha256sum, you'll feel right at home:

Tool Generate Checksum Verify Files
md5sum md5sum file.txt md5sum -c sums.md5
sha256sum sha256sum file.txt sha256sum -c sums.sha256
iscc-sum iscc-sum file.txt iscc-sum -c sums.iscc

Key Advantages

Unlike traditional checksums, ISCC-SUM:

  • 🧠 Are content-aware - similar files produce similar codes
  • 🌐 Follow an ISO standard - ensuring global interoperability
  • ⚡ Process files 50-130x faster than the ISO reference implementation

🚀 What's Next?#

Explore Further