Suite Installation & Deployment

Standalone launcher, hardware-accelerated runtime provisioning, and developer setup.

PyPottery Suite Installation

The PyPottery Suite ships as a self-contained application hub. The launcher provisions an isolated Python environment, detects available hardware acceleration (NVIDIA CUDA, Apple Silicon MPS, AMD ROCm, or CPU), and runs each of the five suite modules as an independent process.

Method A: Launcher Hub

A packaged release with no Python installation, Git, or terminal use required. The launcher bootstraps dependencies, configures a hardware-matched PyTorch backend, and opens a browser-based control panel.

Recommended for researchers

Method B: Source & CLI

Install directly from GitHub. For developers, computational archaeologists building custom pipelines, and contributors extending the machine learning modules via the launcher's Developer Mode.

Developers

Method A: Launcher Hub

Install for your operating system

Select your operating system to download the launcher and follow the step-by-step instructions:

Windows 10 / 11

64-bit (x86_64) • ~28 MB installer

Installer with a setup wizard — Start Menu and Desktop shortcuts are created for you. Portable, no-installer versions are also available on the releases page.

Download Windows Installer

Download and run the installer

Download PyPottery-Launcher-Setup.exe from GitHub Releases and run it. It's a normal installer with a setup wizard (Welcome → choose folder → Install → Finish) — no admin rights needed, it installs to your own user profile, and it registers a proper uninstaller in Add or remove programs.

Launch it

The installer already created a Start Menu entry and a Desktop shortcut for you. Open either one — it starts a local web server and opens your browser to http://127.0.0.1:5000.

First-run environment setup

Click "Configure Environment" in the browser interface. The launcher detects your GPU or CPU, provisions an isolated Python runtime, and installs the matching PyTorch build. Later launches start immediately.

Windows SmartScreen warning

GitHub release binaries aren’t signed with an enterprise code-signing certificate, so Windows Defender SmartScreen may show “Windows protected your PC”. Click “More info”, then “Run anyway”.

Prefer a portable version?

Two no-installer alternatives sit on the same releases page: PyPottery-Launcher-Windows-v1.2.0.zip (extract, then run PyPottery.bat) and PyPottery-Launcher-Windows-EXE-v1.2.0.zip (extract, then run PyPottery.exe directly). Both skip the installer entirely — useful on a locked-down machine. Unlike the installer, they don’t create shortcuts for you; right-click the executable and choose Send to → Desktop (create shortcut) if you want one.

Interactive walkthrough

Windows 11 installation walkthrough

macOS Apple Silicon

M1 / M2 / M3 / M4 • .dmg

Native Apple Silicon build, distributed as a .dmg — the standard drag-to-Applications install.

Download macOS arm64

macOS Intel

Intel Mac • .dmg

Build for Intel-based Mac workstations and laptops, distributed as a .dmg.

Download macOS Intel

Download the .dmg

Download PyPottery-Launcher-macos-arm64.dmg (Apple Silicon: M1–M4) or PyPottery-Launcher-macos-x86_64.dmg (Intel), then open it.

Drag to Applications

The .dmg opens a window with PyPottery Launcher.app next to an Applications shortcut — drag one onto the other. This is the standard macOS install, and it's what avoids Gatekeeper's "App Translocation" issue in the first place.

Launch from Applications

Open PyPottery Launcher.app from /Applications. On Apple Silicon, PyPottery initializes the Metal Performance Shaders (MPS) backend automatically. Environments, model caches, and logs live in ~/Library/Application Support/PyPottery.

“Developer cannot be verified”

macOS may block software downloaded outside the App Store with “PyPottery Launcher cannot be opened because the developer cannot be verified”.

GUI: right-click (or Control-click) PyPottery Launcher.app, choose Open, then confirm.

Terminal: clear the quarantine attribute:

xattr -cr /Applications/"PyPottery Launcher.app"

Opened it straight from Downloads?

If the app runs from a translocated or quarantined location instead of /Applications, PyPottery notices and offers a dialog to move itself there for you — no manual Terminal work required. Installing from the .dmg above avoids the situation from the start, since it’s already pointing you at /Applications.

Portable version

A plain .zip of the same app (PyPottery-Launcher-macos-arm64.zip / -x86_64.zip) is also on the releases page, for anyone who’d rather place the app manually than use the .dmg.

Interactive walkthrough

macOS installation walkthrough

Linux x86_64

AppImage

Self-registering AppImage — adds its own menu entry and icon on first run, no separate install step.

Download Linux AppImage

Download the AppImage

Download PyPottery-Launcher-linux-x86_64.AppImage from GitHub Releases, then make it executable:

chmod +x PyPottery-Launcher-linux-x86_64.AppImage

Run it

./PyPottery-Launcher-linux-x86_64.AppImage

On first run it registers its own menu entry and icon (GNOME, KDE, XFCE) automatically — no separate install script needed. To remove the menu entry later, run ./PyPottery-Launcher-linux-x86_64.AppImage --uninstall-desktop.

FUSE requirement on recent distributions

AppImage requires FUSE 2. Recent distributions (Ubuntu 24.04+, Debian 12+, Fedora 40+) don’t ship libfuse2 by default. If the AppImage fails to start:

# Ubuntu / Debian / Linux Mint:
sudo apt update && sudo apt install -y libfuse2

# Fedora / RHEL:
sudo dnf install -y fuse-libs

# Arch Linux:
sudo pacman -S fuse2

Prefer a plain directory to an AppImage?

PyPottery-Launcher-linux-x86_64.zip, on the same releases page, extracts to a normal directory instead — useful if AppImages aren’t an option on your system:

unzip PyPottery-Launcher-linux-x86_64.zip -d ~/PyPottery
cd ~/PyPottery
chmod +x PyPottery.sh install_desktop.sh
./install_desktop.sh   # optional: adds a menu entry
./PyPottery.sh          # installs missing dependencies on first run, then starts the launcher

Interactive walkthrough

Linux AppImage walkthrough

First run and offline use

Offline use in the field

PyPottery runs offline by default once set up. The first run is the main exception: initial environment setup and AI model downloads require an internet connection.

One module-level exception applies beyond first run: PyPotteryLens currently uses a cloud LLM (OpenRouter) for metadata extraction, so that specific feature needs a live connection every time it’s used, not just once. Everything else in the suite runs locally.

The Suite Launcher

The launcher is a local process supervisor reachable in the browser at http://127.0.0.1:5000.

Launcher control panel walkthrough

What it handles

Environment lifecycle: creates and validates an isolated virtual environment (pypottery_env), keeping tool dependencies separate from your system’s global libraries.
Hardware detection: identifies available compute (CUDA 11.8–12.6, Apple Silicon MPS, AMD ROCm 6.2, or CPU) and installs the matching PyTorch build automatically.
Single-instance lock: an advisory lock prevents duplicate processes or port conflicts; relaunching focuses the existing session instead.
Offline model caching: model weights are downloaded once into models/ and cached for fully offline use afterward.
Process isolation: each application runs as an independent subprocess on its own loopback port. Closing the launcher stops all child processes.

Method B: Source & CLI

For running from a Git checkout or developing custom ML backends:

1. Clone the repository

git clone https://github.com/lrncrd/PyPottery.git
cd PyPottery

2. Create a virtual environment

python -m venv venv

# Windows:
venv\Scripts\activate

# macOS / Linux:
source venv/bin/activate

3. Install dependencies

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

4. Enable Developer Mode

Developer Mode runs the launcher against your local Git checkout instead of downloaded release binaries:

Copy the template configuration:

# Windows:
copy launcher\dev_config.example.py launcher\dev_config.py

# macOS / Linux:
cp launcher/dev_config.example.py launcher/dev_config.py

In launcher/dev_config.py, set:
```
DEVELOPER_MODE = True
```
Run the development server:
```
python -m launcher.gui
```

5. Standalone module installation

To run a single tool outside the launcher, see its dedicated installation guide:

Uninstalling

PyPottery keeps everything in a single folder and installs no services, drivers, or system-wide Python packages, so removing it means deleting that folder. The same folder also holds your projects.

Save your projects first

PyPotteryLens, PyPotteryScan and PyPotteryTrace store each project under apps/<module>/projects/, next to the module’s own files, and PyPotteryInk and PyPotteryLayout keep their exports inside their module folder too. Uninstalling the suite, or a single module, deletes them (updating a module keeps them). Export them first with the Backup button in the launcher’s header (it saves the projects of Lens, Scan and Trace into one .zip), or copy the folders by hand.

Where the data lives, and how to back up your projects

The launcher keeps all its data in one data folder. Where it is depends on how you installed it:

Installation	Data folder
Windows installer	`%LOCALAPPDATA%\PyPottery Launcher`, or the folder you picked in the setup wizard
Windows portable (.zip)	The folder you extracted
macOS (.dmg)	`~/Library/Application Support/PyPottery`, deliberately outside the app, so it survives updates and is not removed when you trash the app
Linux AppImage	The folder that contains the `.AppImage` file (or `~/.local/share/pypottery` if that folder is read-only)
Linux (.zip)	The folder you extracted
Source & CLI	The cloned repository folder

Inside it:

Folder	What it holds
`apps/`	The five modules, each with its own `projects/` folder
`pypottery_env/`	The isolated Python environment, including PyTorch
`python_runtime/`	The Python interpreter the launcher provisions (where present)
`model_cache/`	AI model weights shared by all modules
`shared_assets/`	Files the modules share
`logs/`	Launcher logs

To back up your work, click Backup in the launcher header, choose Export, select the projects and save the .zip somewhere outside the data folder. After a reinstall, open Backup → Import and pick that file; the modules must be installed and stopped.

The Backup covers Lens, Scan and Trace. Anything you want to keep from Ink or Layout (their exports) has to be copied by hand from the module’s folder under apps/. You can also copy a module’s projects/ folder manually, and press Refresh in its Project Repository after putting it back.

Uninstall on Windows

Stop any running module from the launcher panel and quit the launcher, then:

Open Settings → Apps → Installed apps (Apps & features on Windows 10), find PyPottery Launcher and choose Uninstall. The Uninstall PyPottery Launcher shortcut in the Start Menu does the same.
Confirm. The uninstaller stops a running launcher if it finds one, then deletes the installation folder, the Start Menu and Desktop shortcuts, and its entry in Installed apps. It needs no admin rights, just as the installer didn’t.
If %LOCALAPPDATA%\PyPottery Launcher is still there afterwards (antivirus software sometimes holds a file open for a moment), restart Windows and delete the folder by hand.

The portable .zip packages have no uninstaller: delete the folder you extracted, and any shortcut you created yourself.

Uninstall on macOS

Quit PyPottery, open /Applications and drag PyPottery Launcher.app to the Trash.
In Finder choose Go → Go to Folder…, paste ~/Library/Application Support/PyPottery and drag that folder to the Trash. This is what actually frees the disk space: the environment, the model cache and your projects all live there.
Empty the Trash. If you find a ~/Library/Logs/PyPottery folder, it only holds log files and can go too.

The same from the Terminal:

rm -rf "/Applications/PyPottery Launcher.app"
rm -rf "$HOME/Library/Application Support/PyPottery"

Uninstall on Linux

AppImage

Quit PyPottery.
Remove the application-menu entry the AppImage registered for itself, by running it once with a flag:
```
./PyPottery-Launcher-linux-x86_64.AppImage --uninstall-desktop
```
Delete the .AppImage file and the folders next to it (apps/, pypottery_env/, model_cache/, and so on). The AppImage keeps its data beside itself, so deleting only the file leaves several GB behind.

Zip package

Quit PyPottery.

If you ran install_desktop.sh to get a menu entry, remove it:

rm -f ~/.local/share/applications/pypottery.desktop
rm -f ~/.local/share/icons/hicolor/512x512/apps/pypottery.png
rm -f ~/.local/share/icons/hicolor/256x256/apps/pypottery.png
update-desktop-database ~/.local/share/applications 2>/dev/null

Delete the folder you extracted.

Uninstall a Source & CLI install

Stop the launcher (Ctrl+C in the terminal where it runs) and run deactivate if a virtual environment is active.
Delete the cloned PyPottery folder. It holds the virtual environment if you created it there, launcher/dev_config.py, the model cache, and each module’s projects, so copy those first.

A module installed on its own is removed the same way: delete its folder and the virtual environment you made for it.

Remove one module, or free disk space without uninstalling

One module. In the launcher, stop the module if it is running, then click the trash icon on its card and confirm. This deletes the module’s files and its projects, and keeps the AI models already downloaded to the shared model cache. You can install it again from the same card. The option is not available in Developer Mode, where the modules are your own Git checkouts.

Disk space, keeping the suite. Delete part of the data folder instead of all of it:

pypottery_env/: the largest part of the installation. After deleting it, open the launcher and run Configure Environment again to rebuild it.
model_cache/: AI model weights. Each module downloads the models it needs again the next time you use it, so you need an internet connection for that.

Leave apps/ alone unless you mean to remove modules: it holds your projects.

Package caches outside the folder. The tools that install the Python packages (pip and uv) keep their own download caches in your user profile, shared with any other Python software you use. They may hold copies of the large PyTorch packages, and are safe to delete:

	pip cache	uv cache
Windows	`%LOCALAPPDATA%\pip\cache`	`%LOCALAPPDATA%\uv\cache`
macOS	`~/Library/Caches/pip`	`~/.cache/uv`
Linux	`~/.cache/pip`	`~/.cache/uv`

Troubleshooting

Symptom	Cause	Resolution
"Windows protected your PC" (SmartScreen)	No enterprise code-signing certificate — common for open-source releases.	Click "More info", then "Run anyway". One-time per release.
"Developer cannot be verified" (macOS)	Gatekeeper flags apps downloaded outside the App Store or that aren't notarized.	Right-click `PyPottery Launcher.app`, choose Open, confirm. Or run `xattr -cr /Applications/"PyPottery Launcher.app"`.
"Move to Applications?" dialog (macOS)	Launched from a translocated/quarantined copy (e.g. still in `Downloads/`) instead of the installed copy in `/Applications`.	Choose "Move to Applications" in the dialog, or drag the app there yourself and relaunch. Installing via the `.dmg` avoids this from the start.
"AppImage requires FUSE to run" (Linux)	Recent distros (Ubuntu 24.04+, Fedora 40+) don't include FUSE 2 by default.	Install it: `sudo apt install libfuse2` or `sudo dnf install fuse-libs`.
Permission denied on Linux	The executable bit wasn't preserved on extraction.	Run `chmod +x` on the `.AppImage` file, or on `PyPottery.sh` if you're using the zip package.
Environment setup fails or is corrupted	Network interruption during the PyTorch download or package installation.	Delete `pypottery_env/` (or `~/Library/Application Support/PyPottery/pypottery_env` on macOS) and re-run "Configure Environment".
Port already in use	A previous instance crashed without releasing ports 5000–5005, or another local service is using them.	Terminate orphaned Python processes via Task Manager, Activity Monitor, or `pkill -f "launcher.gui"` on Linux.
Deploying to a site with no connectivity	No internet access on-site for the first-run model and package downloads.	Run the launcher and let all five apps and models download while still connected. Once initialized, everything except Lens's metadata extraction runs fully offline.

Ready to install

Download the launcher for your operating system and start producing standardized, publication-ready ceramic documentation.

Download Latest Release (GitHub) Back to Documentation Hub