Download Only the PROJ Data You Need with projsync

You will finish with a read-only inventory and a filtered download of PROJ resource files, without accidentally fetching the complete data set. 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 consume disk space and replace files with the same names, so inspect the dry run first.

1. Check the command and choose a destination

Confirm that the installed command exposes the expected interface:

$ 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. That is convenient for one account, but an explicit directory makes a deployment easier to inspect and repeat:

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

This is an ordinary user operation. If you use a directory owned by root or the system installation, stop before the download and check its ownership. Do not add sudo automatically: it can put the files in a different user's data path and hides which account owns the result.

Checkpoint: the destination should be an empty or deliberately managed directory. If it already contains files, use a new directory for the first run so that the result is easy to review.

2. List candidates without downloading them

Ask the remote catalogue for its file list. This command prints names, areas of use, source IDs and sizes, while --dry-run prevents resource files being downloaded:

$ 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 change over time. On the installed machine, the command completed successfully and returned a CSV-style header followed by entries. The target directory is still not populated by this check.

Use a question mark with a supported filter to discover values before selecting them. For example, this lists source IDs known to the catalogue:

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

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

3. Preview a geographic and source filter

Filters can be combined. This preview selects resources whose source ID contains fr_ign and whose coverage intersects 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 must be between -180 and 180, and latitudes between -90 and 90. A box normally has west less than east; use the documented antimeridian form when the area crosses it.

The default spatial test is intersects, so a resource is selected when its extent touches the box. Choose --spatial-test contains only when the resource extent must be wholly inside the box. The --source-id, --area-of-use, --file and --bbox filters use AND logic. A broad geographic box can still select a large amount of data.

Checkpoint: review the total size and the proposed file names. If they are not what you expected, change the filters and repeat this step. Nothing is downloaded while --dry-run is present.

4. Download the selected resources

Remove only --dry-run after the preview is acceptable:

$ 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. Use --all when you genuinely need every candidate file, but do not use it as a first test: the installed catalogue reported hundreds of files and roughly 705 MB in a dry run. --exclude-world-coverage removes files marked as covering the world from the candidate set.

By default, projsync applies the version metadata in proj.db when deciding which catalogue entries are compatible with this PROJ installation. Keep that behaviour unless you have a specific reason to inspect older or newer entries. --no-version-filtering makes every entry in files.geojson a candidate after the other filters, which can increase the download and introduce data your installed PROJ does not expect.

For a shared installation, --system-directory targets the installation's share/proj directory and normally needs elevated privileges because the launching user must be able to write there. Treat that as a system-wide change: check the planned files first, arrange a backup or package-managed recovery path, then run the command with the required privilege. A user-directory download is easier to undo: remove only the files created by this run, or discard the new directory after confirming no other application uses it.

5. Verify the result and handle failures

Compare the directory with 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 was written 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 if you need an audit trail.

If the command cannot reach the endpoint, check network access and the configured endpoint before retrying. --endpoint URL changes where the master files.geojson catalogue and resources are fetched from; the default comes from PROJ configuration. If a download was interrupted, rerun the same filtered command after checking free space. If the files are wrong, stop using that directory as a PROJ data path and move it aside for investigation rather than deleting evidence. Once you have confirmed that no process needs it, an ordinary user can remove a disposable user directory with rm -rf -- "$HOME/proj-data". Do not run that against a shared or system directory.

If the result is too quiet for troubleshooting, add --verbose. Use --quiet only when a calling script deliberately handles status and does not need progress output.