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

> Learn how to handle Unicode characters in filenames for docker-icloudpd using the keep_unicode option. Preserve non-ASCII characters like é ñ or emoji by setting keep_unicode true.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) script generates the runtime configuration profile. At line 115, it explicitly sets the default value:

```bash
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) reads the configuration during startup. At line 88, it logs the current value for debugging purposes:

```bash
log_info " | Keep Unicode: ${keep_unicode}"

```

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

```bash
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:

```bash

# 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.

```yaml

# docker-compose.yml

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

```

Or via Docker CLI:

```bash
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:

```bash
./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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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.