Download Only the PROJ Data You Need with projsync

projsync can quietly pull hundreds of megabytes onto your disk if you skip the dry run first. The examples use projsync from PROJ 9.4, installed here as package version proj-bin 9.4.0-1build2.

Allow about fifteen minutes, including time for the remote catalogue and selected files to download. You need the PROJ utilities package and network access to the configured download endpoint. The commands below write to a directory you choose. They do not alter a service, but a real download can eat disk space and overwrite files with the same names, so inspect the dry run first.

1. Check the command and choose a destination

Confirm the installed command exposes the interface you expect:

$ projsync --help

The installed synopsis includes --target-dir, --dry-run, --list-files, geographic filters and version filtering. The default destination is the user-writable PROJ data directory, which is convenient for one account but harder to inspect and repeat. An explicit directory fixes that:

$ mkdir -p "$HOME/proj-data"
$ test -d "$HOME/proj-data" && printf '%s\n' 'Destination is ready'

This is an ordinary user operation. Pointed at a directory owned by root or the system installation? Stop before the download and check its ownership. Do not add sudo out of habit: it can dump the files into a different user's data path and hides which account actually owns the result.

2. List candidates without downloading them

Ask the remote catalogue for its file list. This prints names, areas of use, source IDs and sizes, while --dry-run stops any resource file actually downloading:

$ projsync --list-files --dry-run --target-dir "$HOME/proj-data"
filename,area_of_use,source_id,file_size
ar_ign_README.txt,,ar_ign,756
...

The exact rows and catalogue size shift over time. On the installed machine, the command completed cleanly and returned a CSV-style header followed by entries. The target directory is still empty after this check.

Use a question mark with a supported filter to see the valid values before you pick one. This lists source IDs the catalogue knows about:

$ projsync --source-id '?' --list-files --dry-run --target-dir "$HOME/proj-data"

In this quoted form the question mark is a value handed to projsync, not a shell wildcard. The same discovery trick works with --area-of-use '?' and --file '?'.

3. Preview a geographic and source filter

Filters combine. This preview selects resources whose source ID contains fr_ign and whose coverage touches a point near Paris:

$ projsync \
    --source-id fr_ign \
    --bbox 2,49,2,49 \
    --dry-run \
    --target-dir "$HOME/proj-data"
Downloading from https://cdn.proj.org into /home/example/proj-data
Total size to download: ...
Would download ...

The four bounding-box values are west longitude, south latitude, east longitude and north latitude, in degrees. Longitudes run -180 to 180, latitudes -90 to 90. West should normally be less than east; use the documented antimeridian form when your area crosses it.

The default spatial test is intersects, so a resource is selected the moment its extent touches the box. Reach for --spatial-test contains only when the resource extent must sit wholly inside the box. --source-id, --area-of-use, --file and --bbox all combine with AND logic, and a broad geographic box can still pull a surprising amount of data.

4. Download the selected resources

Once the preview looks right, drop only --dry-run:

$ projsync \
    --source-id fr_ign \
    --bbox 2,49,2,49 \
    --target-dir "$HOME/proj-data"
Downloading from https://cdn.proj.org into /home/example/proj-data
Downloading ...

At least one selector is required. --all genuinely fetches every candidate file, so do not reach for it as a first test: the installed catalogue reported hundreds of files and roughly 705 MB in a dry run. --exclude-world-coverage drops files marked as covering the whole world from the candidate set.

By default, projsync applies the version metadata in proj.db to decide which catalogue entries suit this PROJ installation. Keep that behaviour unless you have a specific reason to poke at older or newer entries. --no-version-filtering makes every entry in files.geojson a candidate after the other filters, which can both grow the download and hand you data your installed PROJ was not built to expect.

For a shared installation, --system-directory targets the installation's share/proj directory and normally needs elevated privileges, because the launching user has to be able to write there. Treat that as a system-wide change: check the planned files first, line up a backup or package-managed recovery path, then run it with the privilege it needs. A user-directory download is much easier to undo: remove only the files this run created, or bin the new directory entirely once you have confirmed no other application uses it.

5. Verify the result and handle failures

Compare the directory against the filtered inventory:

$ find "$HOME/proj-data" -maxdepth 1 -type f -printf '%f\n' | sort
$ projsync --list-files --target-dir "$HOME/proj-data" \
    --source-id fr_ign --bbox 2,49,2,49

The first command checks what actually landed locally. The second re-reads the catalogue and shows the matching records. A successful download should leave the expected resource names in the destination, but the catalogue can change between runs, so keep the dry-run output around if you need an audit trail.

Too quiet to troubleshoot? Add --verbose. Use --quiet only when a calling script deliberately handles status and does not need progress output.