PicNaru Help

For PicNaru 1.0 · Updated September 30, 2026

Developer: Bluemaker
Contact: [email protected]
한국어 도움말

What PicNaru does

You need your own Immich server to use PicNaru. It brings the new photos and videos you back up to Immich from your phone into the Photos app on your Mac.

Immich backup on your phone → your own Immich server → PicNaru → Photos on your Mac → iCloud Photos sync, if you use it

You need a Mac and a separate Immich server. PicNaru doesn’t include a server, server hosting, or iCloud storage, and you never enter your Apple Account password in PicNaru.

When PicNaru “adds” an item, it means the item was placed in your Mac Photos library. Apple’s Photos app then handles any iCloud upload; PicNaru doesn’t confirm that the upload finished.

Getting started: try one small photo first

1. Sign in to your Immich server

In a web browser on your Mac, open your Immich server and sign in. Make sure the photos you took on your phone appear there too. Backup from your phone to the server is set up in Immich.

PicNaru’s default server address, http://127.0.0.1:2283, means a server running on this Mac. If your server is on a NAS, another computer, or the cloud, replace it with that server’s address. The default address alone doesn’t connect or start any transfer.

Use HTTPS for servers outside your home. Local HTTP isn’t encrypted either. PicNaru uses HTTP only for local addresses you’ve explicitly allowed, and it refuses public HTTP addresses.

2. Create an API key for PicNaru

In the Immich web app, click your profile icon at the top right and go to Account Settings → API Keys. The wording and layout may differ by server version. Immich user settings

When you create the key, select exactly these three permissions:

You don’t need an admin account, the all permission, or upload or delete permissions. Don’t turn on every permission to fix an error. Treat the key like a password and never send it in chat, email, or screenshots.

If you lose the key, create a new one in your Immich account. Check which app uses each key, and revoke only keys you no longer use.

3. Connect the server address and key

In PicNaru, enter the address and API key under 1. Photo Server Connection. To change a saved connection, first turn off Auto Transfer, then click Change Address or API Key.

You can use the Paste buttons next to the fields. The API key is hidden on screen after you enter it. Click Verify Connection and Save on This Mac to verify the account and store the key in this Mac’s keychain. Pasting alone doesn’t save anything or turn on Auto Transfer. To stop editing, click Cancel Changes.

A successful connection check doesn’t yet prove that originals can be downloaded. The first transfer below checks that too.

4. Allow adding to Photos

Click 2. Mac Photos Access → Allow Adding Photos, read the macOS prompt, and allow it. PicNaru needs only permission to add photos. It doesn’t ask to read your whole library or delete anything.

To see items in iCloud too, open Photos on your Mac, check the System Photo Library in Settings → General, and turn on iCloud → iCloud Photos. Don’t switch libraries you already use without thinking it through. You also need enough Mac and iCloud storage and an internet connection. About the System Photo Library

5. Turn on Auto Transfer

Click Turn On Auto Transfer…, read what will be transferred and the conditions, then click Agree and Turn On. If background permission is needed, click Open Background Settings, allow PicNaru, then click Refresh Status. You don’t need to turn off security settings or reset any permission database.

Check that the top of the window says Auto Transfer On · Waiting for Next Check. If it still says “Background Start Needs Checking” or shows an error, don’t treat it as working yet; follow that message first.

6. After turning it on, upload a new photo and a short video

Upload your first test photo to your Immich account after turning on Auto Transfer. Confirm the upload finished on the server, keep your Mac on, and wait for the next check. PicNaru checks about every 15 minutes, but sleep, macOS scheduling, and file size can make it take longer.

Check Recent Activity in PicNaru and look in Photos on your Mac. Items appear by the date they were taken, so even if one was added today, look at its original date or at recently added or imported items. Once a photo arrives, try a small video and check that it plays with sound.

Refresh Status only updates what the app shows; it doesn’t start a transfer. Don’t let another relay tool and PicNaru send the same photos at the same time.

Which items does PicNaru bring over?

PicNaru transfers your media uploaded to the server after you first turned on Auto Transfer for the saved connection. It goes by upload time, not the date taken, so an old photo uploaded later can still be included. It doesn’t import photos or videos that were already on the server before you first turned it on.

If you turn it off and back on for the same connection, PicNaru keeps the original start point, progress, and unfinished list. Files uploaded while it was off are checked too, as long as they came after the start point.

If you previously agreed to transfer photos only, an update doesn’t extend that to videos. Turn it off and agree to the notice about including videos. Even then, only items after the connection’s original start point are included, which may include videos uploaded before your new agreement.

Quitting the app isn’t the same as turning off Auto Transfer

Auto Transfer works while your Mac is on and you’re logged in. After a restart, you need to log in and your server must be running. Transfers aren’t guaranteed while your Mac is asleep or off.

Reading the status

If Paste doesn’t work

Try the Paste button next to the field first. PicNaru rejects multiple lines, control characters, and text that’s too long. It trims leading and trailing spaces but doesn’t fix stray spaces inside a key.

If you’re connected remotely, copy a short, non-secret sentence and try pasting it into a text editor on the same Mac. If that doesn’t work either, check your remote access app’s clipboard sharing or which account you’re logged in to. Don’t test the clipboard with a real API key or send the key in chat. PicNaru’s Paste button can’t fix remote clipboard syncing itself.

If photos or videos don’t appear

1. In the Immich web app, check that the upload finished.
2. Check that the file belongs to the connected account and was uploaded after the start point.
3. In PicNaru, check the on/off status, the time of the last check, and any errors.
4. Check that your Mac is awake, logged in, and can reach the server.
5. Check PicNaru’s Photos permission and your free space. In your library, look at the date the item was taken.
6. If an item is on your Mac but missing on other devices, check your iCloud Photos settings, storage, and sync status. You don’t need to start by creating a new key.

Supported files and limits

PicNaru doesn’t approve videos by comparing codec names to a fixed list. It checks, without changing the original, that the video and audio can be read to the end. Because the macOS decoders and the Photos app may support different things, passing the check doesn’t guarantee that Photos will accept every file. PicNaru doesn’t convert files.

Not supported: RAW, restoring the motion or effects of Live Photo pairs, fragmented MP4 for streaming, and videos with external file references or encryption. Internal structures PicNaru can’t check yet, or damaged files, may also stop a transfer. If your server returns the video part of a Live Photo as a separate item, it may be added as a regular video if it meets the requirements, but the pair isn’t restored.

There’s no overall limit on the number of items transferred or how long you can use PicNaru. Each run handles up to 50 items, including skipped items that were already processed. The rest carry over to the next run. Server queries and storage also have safety limits, so PicNaru isn’t “unlimited and never stops.”

If it stopped on an unsupported video

A file named MP4 doesn’t mean every video inside has the same format. Don’t delete the original or just rename the extension. Start by checking the file size, length, and whether it plays on macOS.

If you decide not to auto-transfer that item, you can use Exclude This Item from Auto Transfer… → Exclude This Item while Auto Transfer is off. This doesn’t delete the original on the server or in Photos. However, you can’t undo an exclusion in the current app, and you’ll need to move the file manually if you need it. After excluding, turn Auto Transfer back on to continue.

“Previous Results Need Review” appears

PicNaru stopped to prevent duplicates because it isn’t sure whether a photo was added just before an interruption.

1. Click Review Previous Results…, read the notice and the total count, and check your actual Photos library. If work is in progress or the status can’t be read, wait before confirming.
2. Reviewed — Don’t Resend Automatically doesn’t mark uncertain items as successful or send them again. Reviewed items won’t be sent again automatically; if they’re not in your library, move them manually. Even if only some items are listed, your confirmation can apply to the whole set, so check the total count.
3. After you confirm, Auto Transfer stays off. Turn it back on to continue. The original start point and unfinished list are kept.

If the same original shows up on the server under a new ID, PicNaru may stop again. That doesn’t mean a new duplicate was sent. Check your library first, and exclude just the current item if needed. Don’t delete record folders or reset the app to fix this.

What PicNaru stores on this Mac

None of this is sent to us. The next two sections explain how to delete it. See the Privacy Policy for details.

To delete a connection and its API key

1. Turn off Auto Transfer and make sure nothing is in progress and no results need review.
2. Click Delete Connection… → Delete Connection from This Mac. If it succeeds, the current connection’s key is deleted from this Mac, but the duplicate-prevention records stay. If you see an error, don’t assume it was deleted.
3. To remove server access too, revoke the key in Immich. First check whether another app uses the same key.

Deleting the app or a connection doesn’t delete every past key, transfer record, or backup copy. Files already in Photos are managed separately. Privacy Policy

To stop using PicNaru and delete everything on this Mac

1. Click Turn Off Auto Transfer and confirm it’s off.
2. Under 1. Photo Server Connection, click Delete All PicNaru Data on This Mac…, read the notice, and click Delete All.
3. This deletes the API keys for all connections, the start points and progress, and the duplicate-prevention, exclusion, and review records stored on this Mac. It can’t be undone.
4. To remove server access too, revoke the PicNaru key in Immich.

After you reconnect and turn on Auto Transfer, PicNaru starts from a new start time. Items uploaded before that time won’t be transferred automatically, even if they were never transferred. This doesn’t delete photos and videos in your Photos library, the API keys and originals on your server, backup copies such as Time Machine, or macOS diagnostic logs. If you’re told the background registration couldn’t be confirmed as removed, you can turn off PicNaru in System Settings → General → Login Items.

This isn’t a troubleshooting tool. If transfers stop, follow the recovery steps above first.

Contact us

Email [email protected] with the following to help us find the problem. Support emails may be stored on Google (Gmail) servers in other countries; see the Privacy Policy.

• Your PicNaru, macOS, and Immich versions, and roughly when the problem happened
• The error message with any secrets removed, and whether the item reached Photos on your Mac
• For video problems: the file extension, approximate size and length, and the codec if you know it

Don’t send API keys, login passwords, original photos or videos, or full diagnostic files. PicNaru is made by Bluemaker.