[Feature] Let immich upload check what's already on the server without uploading (e.g. --no-upload)

[DevJake]

I have searched the existing feature requests, both open and closed, to make sure this is not a duplicate request.

• Yes

The feature

immich upload --delete and --delete-duplicates only ever run as a side effect of an upload, so checking a directory against the server and acting on what's already there means uploading every new file in it first. There's no way to ask "which of these do I already have?" and act on the answer without that.

uploadBatch already computes exactly the split this would need (packages/cli/src/commands/asset.ts:69–78):

const uploadBatch = async (files: string[], options: UploadOptionsDto) => {
  const { newFiles, duplicates } = await checkForDuplicates(files, options);
  const newAssets = await uploadFiles(newFiles, options);   // <- the only thing in the way
  if (options.jsonOutput) {
    console.log(JSON.stringify({ newFiles, duplicates, newAssets }, undefined, 4));
  }
  await updateAlbums([...newAssets, ...duplicates], options);

  await deleteFiles(newAssets, duplicates, options);
};

checkForDuplicates already produces the newFiles / duplicates split; deleteFiles already knows how to delete duplicates when --delete-duplicates is set. The only thing standing between "check" and "act on what the server already has" is the uploadFiles(newFiles, options) call on line 71. This is proposed as a small flag, not a new subsystem: skip that one call, leave newFiles on disk and reported instead of uploaded, and let --delete-duplicates (and --json-output reporting) act on duplicates exactly as they do today.

Flag naming — three options, with trade-offs:

• --no-upload: matches the existing negated-boolean convention already used in this same command for --no-progress (packages/cli/src/index.ts:89), so it reads consistently next to the other flags. Downside: it reads a little oddly stacked against the subcommand's own name (immich upload --no-upload). One caveat I ran into while implementing it: commander enables a boolean option on env-var presence, so the existing --no-progress precedent means IMMICH_PROGRESS_BAR=false actually disables progress bars rather than enabling them. I named the new variable IMMICH_NO_UPLOAD, after the flag rather than after the negated noun, so presence-means-on reads correctly. That IMMICH_PROGRESS_BAR behaviour looks like a separate pre-existing bug; happy to file it separately if it is not already known.
• --check-only: states the intent more directly, without the double-negative-with-the-subcommand-name feel. Downside: introduces a second name for the same underlying idea ("upload" vs. "check"), and could later be conflated with a hypothetical checksum-only or metadata-only mode.
• Reusing --dry-run: rejected. --dry-run already exists and already suppresses both the upload and the deletion (deleteFiles short-circuits under options.dryRun at asset.ts:469–472). Extending it would change already-documented behaviour rather than add new behaviour, and would remove the "actually delete confirmed duplicates" outcome this request is for.

My preference is --no-upload, for consistency with --no-progress, but I don't feel strongly against --check-only and would defer to the maintainers.

Prior art. I've been running a small standalone tool alongside the CLI that does exactly this: same checksum-based check against /assets/bulk-upload-check, no upload capability at all. A few of its safety choices are worth naming here, split into what's actually in scope for this flag and what isn't:

• In scope / nothing extra needed: the flag only has to gate the existing uploadFiles call above — --delete-duplicates and --delete already do the rest server-side.
• Already covered upstream, no gap: XMP sidecars travelling with their asset on deletion. deleteFiles/findSidecar already does this (asset.ts:447–457, 489–493).
• Worth a separate discussion, not part of this request: my tool defaults to a dry run and, when told to act, moves files to a timestamped quarantine directory with a generated restore script rather than unlinking outright, only unlinking for real behind a second explicit flag. That's a materially bigger change to what --delete/--delete-duplicates do across the whole CLI today (not specific to a "don't upload" flag), would change already-shipped behaviour, and deserves its own proposal and maintainer discussion rather than riding in on this one. I'm not proposing it here.

Platform

• Server (this affects @immich/cli, which is released alongside the server platform in this repo; there's no dedicated CLI checkbox)
• Web
• Mobile

Working implementation

I have this implemented and running, but I have deliberately not opened a PR — I would rather check the idea is wanted before asking anyone to review it. Branch: https://github.com/DevJake/immich/tree/feat/cli-no-upload (one commit, cherry-picks cleanly onto main).

Shape of it:

• --no-upload gates the uploadFiles call, beside the existing dryRun short-circuit it mirrors. checkForDuplicates, updateAlbums, and deleteFiles are untouched.
• Conflicts with --delete (nothing is uploaded, so it is always a no-op) and with --skip-hash (skips the duplicate check, so the command could neither upload nor delete anything). Both are refused by commander rather than silently doing nothing.
• Composes with --dry-run, --album/--album-name, and --watch. Albums work because duplicates carry real server asset ids.
• Test count 43 → 51 on that branch. build, check, lint --max-warnings 0, and format all pass.

I have been running it against my own instance (~624 GiB library) to prune a 20 GB+ directory of mixed new and already-stored media, which is the use case that prompted this.

Happy to adapt the naming, the conflict choices, or the reporting to whatever you would prefer, or to drop it if this is not a direction you want the CLI to go.

LLM usage

Since the PR template asks and it seems only fair to volunteer it here too: the implementation, its tests, and this write-up were produced by an AI coding agent working under my direction and review. I verified the code paths, ran the gate, and did the real-world testing above myself.

[github-actions[bot]]

This discussion has automatically been closed as it is likely a duplicate. We get a lot of duplicate threads each day, which is why we ask you in the template to confirm that you searched for duplicates before opening one. If you're sure this is not a duplicate, please leave a comment and we will reopen the thread if necessary.

[DevJake]

I did search before posting, and again now: I can't find a prior request for this. The related open issues I found (#29349, #30491) are about the web UI's duplicate-detection tool, which is a different feature — this asks for a way to run immich upload's existing duplicate check without uploading, so a directory of mixed new and already-stored files can be pruned without first uploading everything new in it.

Happy to be pointed at the existing thread if there is one; the bot didn't say which it matched.

[bo0tzz]

--dry-run already does what you want.

[DevJake]

--dry-run reports the split, but it doesn't act on it — deleteFiles returns before chunkDelete when dryRun is set (asset.ts:487–490), and uploadFiles short-circuits the same way (asset.ts:346–349). So it prints "would have deleted N" and leaves every file in place, which I'd argue is the right behaviour for a dry run; if it actually deleted things it wouldn't be one.

What I'm after is the other half: skip the upload but do prune the confirmed duplicates. Today --delete-duplicates only runs as a side effect of uploading, so pruning a directory of mixed new and already-stored files means uploading all the new ones first. That's the thing I can't express with the current flags — --dry-run skips both actions, --delete-duplicates requires the upload.

I did consider extending --dry-run and rejected it for exactly the reason above. Implementation is on feat/cli-no-upload if it's of interest, but happy to drop this if it's not a direction you want.

[bo0tzz]

skip the upload but do prune the confirmed duplicates

That's what the hashing step is for. Any normal upload invocation should do exactly that for files that are already on the server.

[DevJake]

That does prune them, but it uploads every new file in the directory to get there, and that's the part I'm trying to avoid.

Concretely: a 20 GB directory of mixed new and already-stored media. --delete-duplicates prunes the duplicates, but only after uploading the ~15 GB of new files first -- and since deleteFiles runs after uploadFiles in uploadBatch, cancelling partway through gives no pruning at all. The deletion is gated on the whole upload completing.

The use case is triage rather than ingest: I want to delete the files the server already has, so that what's left on disk is only what's genuinely new -- then review and sort that remainder myself and upload it deliberately. Uploading it all first and sorting server-side is the opposite of that.

Totally fair if that's too narrow a use case to carry a flag for, in which case I'll keep it in my own build and stop bothering you about it.

[bo0tzz]

Please apply your own brain & words, arguing with an LLM is not worth my time.

[DevJake]

Drafting and discussing with a bot then having it post on my behalf isn't exactly failing to apply my brain or sentiment. Besides, I'm putting in my own time to help improve your software. You're not arguing with an autonomous system with zero human oversight or direction.

In my own words, as you insist:
I have many files I want to process. Some exist on the server already, others do not. I want to remove the duplicates before uploading anything, leaving behind only the non-dupes, so I can sort them first, locally, then upload. So adding a --no-upload flag would let you strip out dupes without uploading anything original, when combined with --delete-duplicates.