Best way to restore ~1000 exact files across many folders?

Support
1

Hi, I am trying to restore about **1000 specific files** from a Duplicati backup.

These files are spread across **many different folders**, mostly under `D:\Music` and `D:\iTunes`, and I already have the exact full paths in a CSV/list.

## What I want to do

I want to restore a list of about **1005 exact files** from about **1 week ago**, overwriting the current copies in place.

This is **not**:

- restoring one folder

- restoring one file type

- restoring one artist/folder subtree

It is a large list of exact files in many different locations.

## The problem

If I restore files **one at a time** with `Duplicati.CommandLine.exe restore “” …`, it works, but it is far too slow.

In my tests, each file restore is taking about **4-5 minutes per file** because each restore appears to:

- check the remote backup

- scan state

- download one or more dblock files

- restore a single file

At that rate, restoring 1005 files takes **multiple days**, which makes no sense because restoring much larger folder-based selections seems faster.

## What I found so far

I captured a HAR from the web UI and found that the **ngclient GUI** is not obviously launching a normal CLI command.

Instead, it submits a request like this:

```http

POST /api/v1/backup/2/restore

Content-Type: application/json

Authorization: Bearer

```

with a JSON payload like:

```json

{

“paths”: [

"D:\\\\Music\\\\file1.m4a",

"D:\\\\Music\\\\file2.mp3",

"D:\\\\iTunes\\\\...\\\\file3.mp3"

],

“passphrase”: null,

“time”: “2026-03-21T15:30:51Z”,

“restore_path”: “”,

“overwrite”: true,

“permissions”: false,

“skip_metadata”: false

}

```

and it returns:

```json

{“Status”:“OK”,“ID”:10}

```

Then the GUI polls:

- `GET /api/v1/task/`

- `GET /api/v1/logdata/poll?..`

So it looks like the GUI is using the **server API**, not simply an exposed CLI command.

## Questions

### 1. Is `POST /api/v1/backup//restore` with a large `paths` array the correct/supported way to do this?

If I already have 1005 exact full paths, is that the intended way to launch one bulk restore job?

### 2. Is the GUI doing anything else special beyond that API call?

For example:

- batching internally

- reusing already-loaded restore state

- using a different restore handler than the CLI

- doing any normalization on the paths or time/version selection

### 3. Is there a supported **CLI equivalent** of this exact multi-file GUI restore?

I originally tried include/exclude based CLI approaches, but they did not behave reliably for this scenario.

Examples of issues:

- exact-path `–include` / `–exclude=*` did not behave as expected

- folder restore with excludes has also seemed unreliable in some cases

So I am looking for the **supported way** to do:

- exact file list

- many folders

- restore in place

- overwrite existing files

- specific restore time/version

### 4. If the API approach is correct, are there any limits or best practices for large `paths` arrays?

For example:

- max request size

- recommended batch size

- whether 1000 paths should be split into chunks

- whether restore by `time` or by `version` is preferable here

### 5. Is there any reason the CLI single-file restore is so much slower than a GUI multi-file restore?

My current theory is that one-file-at-a-time CLI restores are paying the restore startup/scan cost repeatedly, whereas the GUI/API bulk restore pays it once.

If that is correct, I want to avoid the one-file-at-a-time method.

## Environment

- Windows

- Duplicati GUI + ngclient

- Restore target is local files on `D:\`

- Backup backend is SSH/SFTP

- Restore needs to overwrite current corrupted files with older good copies

## What I am looking for

I am mainly looking for the **best supported method** to restore about **1000 exact files across many directories** without:

- clicking around the GUI manually folder-by-folder

- restoring one file at a time

- relying on broad include/exclude folder filters that may restore too much

If the answer is:

- “use the API this way”

- “use this CLI pattern instead”

- “split into N batches of size X”

- “use `version` instead of `time`”

(etc)

that would be extremely helpful.

Thanks for your help!

2

I think my original post was too broad, so here is the core question.

I have about 1005 exact full Windows file paths from the same restore point, spread across many folders under D:\Music and D:\iTunes.

Restoring them one at a time with Duplicati.CommandLine.exe restore ... works, but each run repeats the startup/scan work, so it becomes impractically slow.

How to restore 1005 files quickly (the same way you can with the web ui), without having to go through and individually select 1005 files in different folders manually.

Surely there’s a command to do it. I’ve been able to do it via the method I mentioned in the previous post, but that involves getting a bearer token from the web browser every time I want to run a different command.

3

The basic way is simply paths on CommandLine, but that needs protection for embedded spaces and other things one’s OS might trip over on command line.

OS also has a length limit. My Linux system is willing to do 8 million characters. Windows Command Prompt appears pretty short, and PowerShell a little better.

One way to get lots of characters and not worry about shell processing is to use
Using the Command line tools from within the Graphical User Interface e.g. with
Commandline option for that job. Change it to restore and paste paths into the
Commandline arguments, one path per line, without quotes or anything special.

If that doesn’t work, the include method works for me. You didn’t describe your issue enough to comment on. I tried two-path test with parameters-file option.

  --parameters-file (Path): Path to a file with parameters
    Use this option to store some or all of the options given to the
    commandline client. The file must be a plain text file, and UTF-8
    encoding is preferred. Each line in the file should be of the format
    --option=value. Use the special options --source and --target to
    override the localpath and the remote destination uri, respectively.
    The options in this file take precedence over the options provided on
    the commandline. You cannot specify filters in both the file and on the
    commandline. Instead, you can use the special --replace-filter,
    --append-filter, or --prepend-filter options to specify filters inside
    the parameter file. Each filter must be prefixed with either a + or a
    -, and multiple filters must be joined with ;.
    * aliases: --parameter-file, --parameterfile

The --replace-filter with a series of include plus sign worked (in my test).
The --source did not, but the code looks like that’s meant only for backup use.
It looks like it meant to explain that “misuse”, but I don’t think I got that message.

I also had luck with a run-script-before, but on Windows I think it’s semicolon instead of colon to separate. This is usually OS dependent. May be a bug in help.

Scripts

REM DUPLICATI__LOCALPATH
REM This is the path to the folders being backed up or restored. This variable
REM is empty operations  other than backup or restore. The local path can 
REM contain : to separate multiple folders. This value can be changed by echoing
REM --localpath = "new value".

I didn’t test changing filters in run-script-before script, but it might also work.

All of the file or command-line methods need some massaging of the paths into correct format (often a single line) with an editor or other tool (easier on Linux?).

If you can massage your “CSV/list” into path-per-line, pasting might be simplest.
Be sure to check your results because I certainly haven’t tested using 1005 files.

EDIT 1:

If you want a particular --version you can get that number from Restore GUI.