OpenSAK — Open Source Swiss Army Knife for Geocaching

A modern, cross-platform geocaching management tool for Linux, Windows and macOS — a free, open source successor to GSAK, built in Python.

⚠️ Hobby Project Notice

This project is developed in my spare time as a personal hobby project. Bug reports and suggestions are welcome via GitHub Issues, but responses and updates are not guaranteed. Development happens when time and interest allow.

Pull requests are welcome, though they may not always be reviewed or merged.

The software is provided as-is, without warranty or guaranteed support.

Features

Import & Database

📥 Import GPX files and Pocket Query ZIP files from Geocaching.com
🗄️ Multiple databases — keep regions separate (e.g. Zealand, Bornholm, Cyprus)
📍 Home points — save multiple named home points (Home, Cottage, Hotel…) and switch instantly from the toolbar
✅ Update finds from a reference database (e.g. your "My Finds" PQ)

Trip Planning

🗺️ Trip Planner (Ctrl+T) — plan a geocaching trip in two modes:
- Radius — find caches within a set distance from your active home point; sort by distance, difficulty, terrain, date or name
- Route A→B→… — find caches along a multi-point route (up to 10 waypoints); caches sorted in driving order along the route
Route points can be typed in any coordinate format or picked from your saved home points
Preview on map — open selected trip caches on an interactive map with one click
Export trip caches directly to GPS or as a GPX file

View & Navigation

🗺️ Interactive map with OpenStreetMap and colour-coded cache pins with clustering
🔍 Advanced filter dialog — 3 tabs: General, Dates and Attributes (~70 Groundspeak attributes)
📊 Configurable columns — 17+ columns, toggle on/off
🎨 Status icons in list — ✅ found, ❌ DNF, 🔒 archived, ⚠️ unavailable
🔗 Click GC code → opens cache page on geocaching.com
🗺️ Click coordinates → opens in Google Maps or OpenStreetMap

Cache Details

📋 Cache details — description, hints and logs
🔓 ROT13 hint decoding — one click to decode / re-hide the hint
🔍 Search in logs — real-time search with match highlighting
📍 Corrected coordinates — store solved puzzle coordinates per cache; used in GPS export and shown on map
✏️ Add / edit / delete caches manually

Right-click Menu

🌐 Open on geocaching.com
🗺️ Open in map app (Google Maps / OpenStreetMap)
📋 Copy GC code / coordinates (in your chosen format)
☑ Mark as found / not found
📍 Add / edit / clear corrected coordinates
⇄ Open coordinate converter directly from the cache list

GPS Export

📤 Send to Garmin GPS — auto-detects USB-mounted Garmin devices
🗑️ Optional: delete existing GPX files on device before upload
💾 Save as GPX file — export to any location

Geocaching Tools

⇄ Coordinate Converter — convert between DD, DMM and DMS formats with one click
📐 Coordinate Projection — calculate a new coordinate from bearing and distance
🔢 Digit Checksum — sum all digits in a coordinate (N/S and E/W separately)
⊕ Midpoint — find the great-circle midpoint between two coordinates
📏 Distance & Bearing — distance and azimuth between two coordinates
All tools open pre-filled with the currently selected cache's coordinates

Language Support

🌍 Danish, English and French built in
🔧 Easy to add new languages — copy one file, translate, done

Known Limitations (Beta)

Favourite points cannot be imported from GPX/PQ files (requires Geocaching.com API)
No Geocaching.com Live API integration
GPS auto-detection on Linux may not find all Garmin devices automatically
macOS builds are not signed with an Apple Developer certificate (right-click → Open on first launch)

System Requirements

Platform	Requirement
Linux	Ubuntu 20.04+ / Linux Mint 20+ / Debian 11+
Windows	Windows 10 or newer
macOS	macOS 11 (Big Sur) or newer
Python	3.10 or newer
Disk space	~500 MB (including PySide6)

Installation

🐧 Linux — Automatic installer (recommended)

The easiest way to install OpenSAK on Linux. The script installs all dependencies, downloads OpenSAK, and creates a shortcut in your application menu automatically.

curl -fsSL https://raw.githubusercontent.com/AgreeDK/OpenSAK/main/scripts/install-opensak.sh | bash

The installer will:

Check and install required system packages (python3, git, libxcb-cursor0 etc.)
Clone the repository to ~/opensak
Set up a Python virtual environment
Create an entry in your application menu
Optionally create a desktop shortcut
Offer to start OpenSAK immediately when done

Manual install: If you prefer to install manually or the script does not work on your distribution, see the manual Linux instructions below.

🪟 Windows — Standalone installer (recommended)

Download the latest OpenSAK-Windows.zip from the Releases page, unzip it, and double-click OpenSAK.exe — no Python or Git installation required.

🍎 macOS — App bundle (recommended)

Download the correct .dmg for your Mac from the Releases page:

Mac type	File to download
Apple Silicon (M1/M2/M3/M4)	`OpenSAK-macOS-arm64.dmg`
Intel	`OpenSAK-macOS-x86_64.dmg`

Not sure which Mac you have? Click the Apple menu () → "About This Mac". If it says "Apple M1/M2/M3/M4" choose arm64. If it says "Intel" choose x86_64.

Open the .dmg and drag OpenSAK to your Applications folder.

On first launch, macOS may block the app because it is not signed with an Apple Developer certificate. Right-click → Open to bypass this warning.

Manual installation (all platforms)

Use this method if the automatic installer does not work, or if you prefer to install from source.

Linux (manual)

sudo apt update
sudo apt install git python3 python3-venv python3-pip libxcb-cursor0

cd ~
git clone https://github.com/AgreeDK/opensak.git
cd opensak

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

opensak # or python run.py

Windows (manual)

Install Python 3.10+ from python.org — make sure to check "Add Python to PATH"

Install Git from git-scm.com

cd $env:USERPROFILE
git clone https://github.com/AgreeDK/opensak.git
cd opensak
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
opensak # or python run.py

macOS (manual)

⚠️ macOS is not yet fully tested. Feedback is very welcome!

xcode-select --install   # if not already installed
brew install python git

cd ~
git clone https://github.com/AgreeDK/opensak.git
cd opensak
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
opensak # or python run.py

Diagnostics (opensak-doctor)

OpenSAK includes a diagnostic tool to help troubleshoot installation or environment issues. This is especially useful if the application fails to start or behaves unexpectedly.

After installing OpenSAK, run the following command in your terminal:

opensak-doctor

What it checks:

The diagnostic tool performs several environment checks:
Python version – ensures your system meets the required Python version for OpenSAK.
Virtual environment – checks if you are running OpenSAK inside a virtual environment.
Dependencies – verifies that all required Python packages are installed.
Configuration directory – ensures OpenSAK can create and write to ~/.opensak.

Getting Started

1. Get a Pocket Query from Geocaching.com

Log in at geocaching.com
Go to Pocket Queries in your profile menu
Download a Pocket Query as a .zip file

2. Import into OpenSAK

Start OpenSAK with python run.py
Click Import GPX / PQ zip in the menu bar
Select your .zip file and click Import

3. Set your home location

Go to Settings → Settings
Add one or more named home points (e.g. Home, Cottage, Hotel)
Coordinates can be entered in any format (DMM, DMS or DD)
Activate the home point you want to use — or switch from the toolbar dropdown
Choose your preferred coordinate format and map app

4. Filter and find caches

Quick filter — dropdown at the top of the window
Advanced filter — click 🔍 Filter in the toolbar (Ctrl+F)
- General, Dates and ~70 Groundspeak attributes
- Save filter profiles for reuse

5. Plan a trip

Click 🗺️ Trip Planner in the toolbar (Ctrl+T)
Choose Radius to find caches near your home point, or Route to find caches along a drive
Adjust criteria — the preview updates live
Click 🗺️ Show on map to visualise the selection
Export to GPS or save as GPX file

Updating Finds from "My Finds"

Download your "My Finds" Pocket Query from geocaching.com
Create a new database called "My Finds" in OpenSAK
Import the My Finds ZIP file into that database
Switch back to the database you want to update
Go to Settings → Update finds from reference database

Changing the Language

Go to Settings → Settings
Select your language in the Language section
Restart OpenSAK — the new language takes effect on next startup

Currently supported: Danish (da), English (en), French (fr), Portuguese (pt)

Adding a New Language

Copy src/opensak/lang/en.py to e.g. src/opensak/lang/de.py
Translate the string values (keys must not be changed)

Register the language in src/opensak/lang/__init__.py:

AVAILABLE_LANGUAGES = {
    "da": "Dansk",
    "en": "English",
    "fr": "Français",
    "de": "Deutsch",   # ← add this line
}

Submit a Pull Request — contributions welcome!

Updating to the Latest Version

If you used the automatic Linux installer

cd ~/opensak
git pull origin main
source .venv/bin/activate
pip install -r requirements.txt
python run.py

If you downloaded a release (.exe / .dmg / AppImage)

Download the latest version from the Releases page and replace your existing installation.

If you installed manually from source

cd ~/opensak
source .venv/bin/activate      # Linux/macOS
# .venv\Scripts\activate       # Windows

git pull origin main
pip install -r requirements.txt
python run.py

Uninstalling OpenSAK

OpenSAK does not have an installer or uninstaller. To remove it completely, delete the following files and folders manually.

Tip: Your geocaching databases are stored inside the data folder below. If you want to keep your data for a future reinstall, back up that folder before deleting it.

🐧 Linux

rm -rf ~/.local/share/opensak/
rm -rf ~/opensak/
rm -f ~/.local/share/applications/opensak.desktop
rm -f ~/Desktop/opensak.desktop

🪟 Windows

rmdir /s /q "%APPDATA%\opensak"

Then delete the folder where you placed OpenSAK.exe.

🍎 macOS

rm -rf ~/Library/Application\ Support/opensak/

Then drag the OpenSAK app from Applications to Trash.

Reporting Bugs

Please use GitHub Issues and include:

Your platform (Linux / Windows / macOS + version)
Python version: python3 --version
The error message from the terminal (if any)

Project Structure

opensak/
├── run.py                          # Entry point
├── requirements.txt
├── scripts/
│   └── install-opensak.sh          # Linux automatic installer
├── src/opensak/
│   ├── app.py                      # Startup + migration
│   ├── config.py                   # Paths + language preference
│   ├── lang/                       # Language files
│   │   ├── __init__.py             # i18n engine (tr() function)
│   │   ├── da.py                   # Danish
│   │   ├── en.py                   # English
│   │   ├── pt.py                   # Portuguese (contributed by @Fabio-A-Sa)
│   │   └── fr.py                   # French (contributed by @theyoungstone)
│   ├── db/
│   │   ├── models.py               # SQLAlchemy ORM models
│   │   ├── database.py             # Session management
│   │   ├── manager.py              # Multiple databases
│   │   └── found_updater.py        # Update finds from reference DB
│   ├── importer/                   # GPX + PQ ZIP importer
│   ├── filters/
│   │   └── engine.py               # 18 filter types, AND/OR, profiles
│   ├── utils/
│   │   ├── run_cli.py              # The primary entry point, launches the GUI/CLI
│   │   ├── run_test.py             # Wrapper to verify the app integrity
│   │   └── doctor.py               # Performs system health checks
│   ├── gps/
│   │   └── garmin.py               # Garmin detection + GPX generator
│   └── gui/
│       ├── mainwindow.py
│       ├── cache_table.py
│       ├── cache_detail.py
│       ├── map_widget.py
│       ├── settings.py
│       ├── coords.py               # Coordinate format conversion (DD/DMM/DMS)
│       └── dialogs/
│           ├── filter_dialog.py            # Advanced filter (3 tabs)
│           ├── import_dialog.py
│           ├── waypoint_dialog.py
│           ├── column_dialog.py
│           ├── database_dialog.py
│           ├── found_dialog.py
│           ├── gps_dialog.py               # GPS export + delete
│           ├── trip_dialog.py              # Trip planner (radius + route)
│           ├── settings_dialog.py
│           ├── corrected_coords_dialog.py  # Corrected coordinates
│           ├── coord_converter_dialog.py   # Geocaching tool: coordinate converter
│           ├── projection_dialog.py        # Geocaching tool: coordinate projection
│           ├── checksum_dialog.py          # Geocaching tool: digit checksum
│           ├── midpoint_dialog.py          # Geocaching tool: midpoint calculator
│           └── distance_bearing_dialog.py  # Geocaching tool: distance & bearing
└── tests/
    ├── test_db.py                  # 13 tests
    ├── test_importer.py            # 11 tests
    ├── test_languages.py           # 3 tests
    └── test_filters.py             # 39 tests

Roadmap

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

MIT License — see LICENSE for details.

Acknowledgements

OpenStreetMap for map tiles
Leaflet.js for the map library
PySide6 / Qt for the GUI framework
SQLAlchemy for the database layer
@theyoungstone (Pierre LEJEUNE) for the French translation
Everyone who has tested the app and provided feedback!

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src/opensak		src/opensak
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS.md		CONTRIBUTORS.md
PRIVACY_POLICY.md		PRIVACY_POLICY.md
README.md		README.md
opensak.spec		opensak.spec
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
run.py		run.py

Folders and files

Latest commit

History

Repository files navigation

OpenSAK — Open Source Swiss Army Knife for Geocaching

Features

Import & Database

Trip Planning

View & Navigation

Cache Details

Right-click Menu

GPS Export

Geocaching Tools

Language Support

Known Limitations (Beta)

System Requirements

Installation

🐧 Linux — Automatic installer (recommended)

🪟 Windows — Standalone installer (recommended)

🍎 macOS — App bundle (recommended)

Manual installation (all platforms)

Linux (manual)

Windows (manual)

macOS (manual)

Diagnostics (opensak-doctor)

Getting Started

1. Get a Pocket Query from Geocaching.com

2. Import into OpenSAK

3. Set your home location

4. Filter and find caches

5. Plan a trip

Updating Finds from "My Finds"

Changing the Language

Adding a New Language

Updating to the Latest Version

If you used the automatic Linux installer

If you downloaded a release (.exe / .dmg / AppImage)

If you installed manually from source

Uninstalling OpenSAK

🐧 Linux

🪟 Windows

🍎 macOS

Reporting Bugs

Project Structure

Roadmap

Contributing

License

Acknowledgements

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages