How to Handle Unicode Characters in Filenames with the keep_unicode Option in docker-icloudpd

Set keep_unicode=true in your docker-icloudpd configuration profile or pass KEEP_UNICODE=true as an environment variable to preserve non-ASCII characters like é, ñ, or emoji in downloaded filenames instead of stripping them.

The docker-icloudpd container automates iCloud photo downloads by wrapping the icloudpd binary, but by default it removes Unicode characters from filenames to ensure maximum filesystem compatibility. If you need to retain original characters such as accented letters, symbols, or non-Latin scripts in your photo library, the keep_unicode configuration option controls this behavior directly within the container's shell-based configuration system.

Understanding the keep_unicode Configuration Flow

The keep_unicode setting travels through three distinct stages from container initialization to command execution.

Default Initialization in init_config.sh

When the container first starts, the init_config.sh script generates the runtime configuration profile. At line 115, it explicitly sets the default value:

write_variable keep_unicode false

This ensures that, by default, all non-ASCII characters are removed from filenames to prevent encoding issues on older filesystems.

Runtime Processing in sync-icloud.sh

The main entrypoint sync-icloud.sh reads the configuration during startup. At line 88, it logs the current value for debugging purposes:

log_info " | Keep Unicode: ${keep_unicode}"

Later, at lines 2183-2185, the script checks this variable before assembling the final command line:

if [ "${keep_unicode}" != false ]
   command_line="${command_line} --keep-unicode-in-filenames"

This appends the --keep-unicode-in-filenames flag to the underlying icloudpd binary invocation.

Enabling Unicode Preservation

You can activate Unicode support through three methods, depending on your deployment preferences.

Method 1: Configuration File (profile)

Edit the generated profile file directly. If running with a mounted config volume:

# Edit the profile configuration

echo "keep_unicode=true" >> /config/profile

# Verify the setting

grep keep_unicode /config/profile

Set the value to true to preserve characters like "é", "ñ", "ß", or emoji in downloaded filenames.

Method 2: Environment Variables

When using Docker Compose or CLI deployment, pass the setting as an environment variable. The container initialization scripts automatically map KEEP_UNICODE to the internal keep_unicode variable.

# docker-compose.yml

services:
  icloudpd:
    image: boredazfcuk/docker-icloudpd:latest
    environment:
      - KEEP_UNICODE=true
    volumes:
      - ./downloads:/downloads
      - ./config:/config

Or via Docker CLI:

docker run -e KEEP_UNICODE=true \
  -v ./config:/config \
  -v ./downloads:/downloads \
  boredazfcuk/docker-icloudpd:latest

Method 3: Direct Command Line Override

For debugging or one-time executions, you can manually invoke the sync script with the flag:

./sync-icloud.sh --keep-unicode-in-filenames

This bypasses the configuration file and forces Unicode preservation for that specific run.

Technical Implementation Details

The keep_unicode option ultimately controls the --keep-unicode-in-filenames argument passed to the icloudpd binary. When enabled, the binary retains the original Unicode characters from iCloud metadata instead of transliterating or stripping them. This is particularly important for users with photo libraries containing non-English album names, location tags, or special characters in original filenames.

According to the CONFIGURATION.md documentation at line 108: "Set this to true to keep unicode chars in file names or set it to false to remove all non-ascii chars. Default: false."

Summary

• The keep_unicode option in docker-icloudpd controls whether non-ASCII characters are preserved in downloaded filenames.
• By default, init_config.sh sets keep_unicode=false to ensure filesystem compatibility.
• Set keep_unicode=true in the profile file or pass KEEP_UNICODE=true as an environment variable to retain Unicode characters.
• The sync-icloud.sh script translates this setting into the --keep-unicode-in-filenames flag for the underlying icloudpd binary.

Frequently Asked Questions

What happens if I don't set keep_unicode?

If you do not explicitly configure keep_unicode, the container defaults to false as defined in init_config.sh at line 115. This means all non-ASCII characters (such as accented letters, Chinese characters, or emoji) will be stripped or transliterated from filenames during download, resulting in ASCII-only filenames.

Can I use KEEP_UNICODE instead of editing the profile file?

Yes. The container initialization system maps environment variables to configuration variables. Setting KEEP_UNICODE=true in your Docker Compose file or docker run command achieves the same result as editing keep_unicode=true in the /config/profile file. Both methods result in sync-icloud.sh appending --keep-unicode-in-filenames to the download command.

Does this affect existing downloaded files?

No. The keep_unicode option only affects the filename generation process for new downloads initiated after the setting is changed. Existing files in your download directory retain their current names regardless of this configuration. If you need to rename existing files to include Unicode characters, you would need to manually rename them or re-download the library with the appropriate setting enabled.

Where is the keep_unicode setting logged during sync?

The sync-icloud.sh script logs the current value of keep_unicode during startup at line 88. You will see an entry in the container logs that reads | Keep Unicode: true or | Keep Unicode: false, allowing you to verify that your configuration change has been properly loaded before the download process begins.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}