> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nikaplanet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Download Large Folders from Nika Planet

> Install the Nika Planet Downloader to transfer folders over 2 GiB or 2,000 files, resume interrupted downloads, and verify each file.

Browsers download a folder by building the whole ZIP in memory before anything
reaches your disk. Folders over 2 GiB or 2,000 files can stall, and there is no
way to resume — so Nika Planet hands folders past either limit to a small
terminal tool instead.

The **Nika Planet Downloader** writes straight to the drive you choose, transfers
files in parallel, resumes where it left off, and verifies every file against the
checksum storage reports.

The web app sends large **folders** to the downloader. Individual file
selections continue to use the normal browser download, even when a file is
large. The downloader transfers the objects inside each selected folder
individually; you can also run it directly for folders without starting from
the web app.

<div id="platform-selector" />

## Install

One install covers every export, in any workspace.

<Tabs>
  <Tab title="macOS">
    With [Homebrew](https://brew.sh):

    ```bash theme={null}
    brew install nikageospatial/nika-planet-downloader/nika-planet-downloader
    ```

    It is ready to use as soon as the command finishes. `brew upgrade
        nika-planet-downloader` picks up new versions.

    No Homebrew? Use the install script instead:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NikaGeospatial/nika-planet-downloader/main/install.sh | sh
    ```

    The script adds the downloader to your `PATH`, so **open a new terminal
    window** before running it. Run the script again to update.
  </Tab>

  <Tab title="Windows">
    In PowerShell:

    ```powershell theme={null}
    irm https://raw.githubusercontent.com/NikaGeospatial/nika-planet-downloader/main/install.ps1 | iex
    ```

    It installs to `%LOCALAPPDATA%\Programs\nika-planet-downloader` and adds that
    folder to your `PATH` — no administrator rights needed — and the window you ran
    it in can use the downloader straight away.

    Rather not paste a command? Download
    [`install.cmd`](https://github.com/NikaGeospatial/nika-planet-downloader/releases/latest/download/install.cmd)
    and double-click it, then **open a new PowerShell window** to use the
    downloader. It is not code-signed yet, so Windows may ask you to confirm before
    it runs.

    Run either one again to update. 64-bit Windows only; on Windows on Arm the x64
    build runs under emulation.
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NikaGeospatial/nika-planet-downloader/main/install.sh | sh
    ```

    The script adds the downloader to your `PATH`, so **open a new terminal
    window** before running it. Run the script again to update. x86\_64 only for
    now.
  </Tab>
</Tabs>

## Download a folder

Point the tool at a folder using a `nikafs://` address:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    nika-planet-downloader export 'nikafs://<project-id>/data/stac/cogs' --output ~/Downloads
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    nika-planet-downloader export 'nikafs://<project-id>/data/stac/cogs' --output "$HOME\Downloads"
    ```

    Write the output folder as `"$HOME\Downloads"` rather than `~/Downloads`:
    Windows PowerShell passes `~` to programs unchanged, so the download would land
    in a folder literally named `~`.
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    nika-planet-downloader export 'nikafs://<project-id>/data/stac/cogs' --output ~/Downloads
    ```
  </Tab>
</Tabs>

You do not need to sign in first. If no session is cached, the command opens your
browser once, and continues into the download as soon as you have authorised it.

<Note>
  **`--output` is the parent directory.** The folder structure from Nika Planet
  is recreated inside it, so `--output ~/Downloads` saves the example above to
  `~/Downloads/stac/cogs` (on Windows, `--output "$HOME\Downloads"` saves it to
  `Downloads\stac\cogs` in your user folder). Passing `--output ~/Downloads/stac`
  would give you `~/Downloads/stac/stac`.
</Note>

### Finding the address

The `nikafs://` address is your project id followed by the folder path:

1. **Project id** — the UUID in the workspace URL while the project is open
2. **Folder path** — right-click the folder in File Storage and choose
   **Copy Path**, which gives you something like `/data/stac/cogs/`

Join them: `nikafs://<project-id>/data/stac/cogs`

Addresses do not expire. Keep one in a script or runbook and it will keep working
for as long as you have access to that folder.

### Several folders at once

Pass as many addresses as you like. They may span different projects.

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    nika-planet-downloader export \
      'nikafs://<project-id>/data/stac/cogs' \
      'nikafs://<project-id>/data/imagery/2024' \
      --output ~/Downloads
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    nika-planet-downloader export `
      'nikafs://<project-id>/data/stac/cogs' `
      'nikafs://<project-id>/data/imagery/2024' `
      --output "$HOME\Downloads"
    ```
  </Tab>

  <Tab title="Linux">
    ```bash theme={null}
    nika-planet-downloader export \
      'nikafs://<project-id>/data/stac/cogs' \
      'nikafs://<project-id>/data/imagery/2024' \
      --output ~/Downloads
    ```
  </Tab>
</Tabs>

### Starting from the web app

If you select folders in File Storage and choose **Download**, anything too large
for the browser collapses into a single row in Active Operations. Click
**Download via CLI** for a dialog with the install command and the exact export
command already filled in. It shows the commands for the operating system you
are on; switch between **macOS**, **Windows** and **Linux** at the top if you
are setting up another machine. Copy them and run them.

## Options

| Flag | Default | What it does |
| - | - | - |
| `--output` | required | Parent directory for the download |
| `--concurrency` | `4` | Files transferred at once. Raise it if your connection is not saturated |
| `--force` | off | Re-download files even when a verified local copy exists |
| `--dry-run` | off | List what would transfer, then stop |

<Note>
  The flags above are the ones you are likely to reach for; run
  `nika-planet-downloader export --help` for the full list.
</Note>

## Resuming

Press **Ctrl-C** at any point. Partly-transferred files are kept as `.nikapart`
files, and re-running the identical command picks up where it stopped. Files that
already finished are skipped after a size check, so repeating a command is cheap
and safe.

## Other commands

```bash theme={null}
nika-planet-downloader login     # sign in ahead of time
nika-planet-downloader whoami    # show the current sign-in state
nika-planet-downloader logout    # forget the cached session on this machine
```

## Access and privacy

The tool signs in as **you**. It can only download what your own Nika Planet
account is already allowed to download, and that permission is re-checked on
every request — so if your workspace access changes, an in-progress download
stops. Read access is granted one hour at a time and can be revoked.

Your session is stored in your operating system's credential store — the
Keychain on macOS, Credential Manager on Windows — never in a file.

## If something goes wrong

<AccordionGroup>
  <Accordion title="'command not found' or 'is not recognized'">
    Open a new terminal window. The installer added the downloader to your
    `PATH`, and windows that were already open do not see the change.
  </Accordion>

  <Accordion title="'no folders given, and nothing is waiting on this account'">
    You ran `export` with no address. Pass a `nikafs://` address, or start a
    download from the web app and use **Download via CLI**.
  </Accordion>

  <Accordion title="'No files found under …'">
    The path is wrong or the folder is empty. Re-copy it with **Copy Path** and
    check the project id matches the workspace the folder is in.
  </Accordion>

  <Accordion title="'You do not have permission to download from this workspace'">
    Your access to that project changed. Ask a workspace owner to confirm you
    are still a contributor or above.
  </Accordion>

  <Accordion title="Some files failed">
    Re-run the identical command. Only the files that failed are retried;
    everything already downloaded is skipped.
  </Accordion>

  <Accordion title="Windows: the browser shows 'Sign-in failed — Missing code'">
    Earlier versions of the downloader opened the sign-in page on Windows
    without the details it needs. Re-run the Windows install command to update,
    then sign in again.
  </Accordion>

  <Accordion title="Windows: 'An Application Control policy has blocked this file'">
    Smart App Control, which is on by default on new Windows 11 installations,
    blocks programs it does not recognise yet, and the downloader is not
    code-signed. Windows offers no way to allow a single program past it, so
    run the downloader on another computer, or contact us below.
  </Accordion>

  <Accordion title="Windows: double-clicking install.ps1 does not install anything">
    Windows does not run downloaded PowerShell scripts that way. Use
    `install.cmd`, or paste the `irm … | iex` command from the Windows install
    tab into PowerShell.
  </Accordion>
</AccordionGroup>

Still stuck? Email [support@nikaplanet.com](mailto:support@nikaplanet.com), or
[book a call](https://cal.com/lawrence-nika/export-20-gb-files-from-nika.eco) for
help with very large migrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.