icloud-photos-downloader · AndreyNikiforov · Aug 30, 2025 · Aug 30, 2025 · Aug 30, 2025 · Aug 30, 2025
diff --git a/docs/authentication.md b/docs/authentication.md
@@ -17,7 +17,7 @@ If you want to send notification emails using your Gmail account, and you have e
 ```{versionadded} 1.21.0
 ```
 
-There are two ways to provide MFA code to `icloudpd`:
+There are two ways to provide an MFA code to `icloudpd`:
 - Using console
 - Using web interface
 
@@ -28,7 +28,7 @@ Other options: *webui*
 
 ## Access from Mainland China
 
-Access to iCloud.com is blocked from mainland China. `icloudpd` can be used with [`--domain cn`](domain-parameter) parameter to support downloading iCloud Photos from mainland China, however, people reported mixed results with that parameter.
+Access to iCloud.com is blocked from mainland China. `icloudpd` can be used with the [`--domain cn`](domain-parameter) parameter to support downloading iCloud Photos from mainland China; however, people have reported mixed results with that parameter.
 
 ## FIDO
 
@@ -40,7 +40,7 @@ Advanced Data Protection (ADP) for iCloud accounts is not supported because `icl
 
 ## Occasional Errors
 
-Some authentication errors may be resolved by clearing `.pyicloud` subfolder in the user's home directory. [Example](https://github.com/icloud-photos-downloader/icloud_photos_downloader/issues/772#issuecomment-1950963522)
+Some authentication errors may be resolved by clearing the `.pyicloud` subfolder in the user's home directory. [Example](https://github.com/icloud-photos-downloader/icloud_photos_downloader/issues/772#issuecomment-1950963522)
 
 (password-providers)=
 ## Password Providers
@@ -51,16 +51,16 @@ Some authentication errors may be resolved by clearing `.pyicloud` subfolder in
 WebUI support
 ```
 
-Passwords for iCloud access can be supplied by user in four ways:
+Passwords for iCloud access can be supplied by the user in four ways:
 - Using [`--password`](password-parameter) command line parameter
 - Using keyring
 - Using console
 - Using web interface
 
-It is possible to specify which of these three ways `icloudpd` should use, by specifying them with [`--password-provider`](password-provider-parameter) parameter. More than one can be specified and the order
-of providers matches the order then will be checked for password. E.g. `--password-provider keyring --password-provider console` means that `icloudpd` will check password in keyring first and then, if no password found, ask for password in the console.
+It is possible to specify which of these four ways `icloudpd` should use, by specifying them with the [`--password-provider`](password-provider-parameter) parameter. More than one can be specified and the order
+of providers matches the order they will be checked for a password. E.g., `--password-provider keyring --password-provider console` means that `icloudpd` will check the password in the keyring first and then, if no password is found, ask for a password in the console.
 
-Keyring password provider, if specified, saves valid password back into keyring.
+The keyring password provider, if specified, saves the valid password back into the keyring.
 
 Console and Web UI are not compatible with each other. Console or WebUI providers, if specified, must be last in the list of providers because they cannot be skipped.
 
@@ -90,7 +90,7 @@ Use `icloud`, not `icloudpd`
 (multiple-accounts-and-configs)=
 ## Using Multiple Accounts and Config
 
-`icloudpd` can process iCloud collections for multiple accounts or use multiple configs for one account. This is achived by specifying `--username` parameter multiples times: any options specified after `--username` will be applied to mentioned user only. Parameters specified before first `--username` work as defaults for all other user configs. Global app-wide settings can be specified anywhere.
+`icloudpd` can process iCloud collections for multiple accounts or use multiple configs for one account. This is achieved by specifying the `--username` parameter multiple times: any options specified after `--username` will be applied to the mentioned user only. Parameters specified before the first `--username` work as defaults for all other user configs. Global app-wide settings can be specified anywhere.
 
 ### Example: using two user accounts
 
@@ -100,10 +100,10 @@ $ icloudpd --use-os-locale --cookie-directory ./cookies --username alice@apple.c
 
 Explanation
 
-- `--use-os-locale` is global parameter and can be used anywhere
-- `--cookie-directory` is a default for both users; it is okay to use same folder since session and coockies are stored in files based on user name, so they would not collide
-- `--directory ./alice` is specifying that all photos for Alice will be downloaded into ./alice folder
-- `--directory ./bob` is specifying that all photos for Alice will be downloaded into ./alice folder
+- `--use-os-locale` is a global parameter and can be used anywhere
+- `--cookie-directory` is a default for both users; it is okay to use the same folder since sessions and cookies are stored in files based on the user name, so they would not collide
+- `--directory ./alice` specifies that all photos for Alice will be downloaded into the ./alice folder
+- `--directory ./bob` specifies that all photos for Bob will be downloaded into the ./bob folder
 
 ### Example: using two configs for one account
 
@@ -114,9 +114,9 @@ $ icloudpd --cookie-directory ./cookies --username alice@apple.com --directory .
 Explanation
 
 - `--cookie-directory` is a default for both configs
-- `--directory ./photos --skip-videos` is specifying that all photos for Alice will be downloaded into ./photos folder
-- `--directory ./videos --skip-photos` is specifying that all videos for Alice will be downloaded into ./videos folder
-- `--use-os-locale` is global parameter and can be used anywhere
+- `--directory ./photos --skip-videos` specifies that all photos for Alice will be downloaded into the ./photos folder
+- `--directory ./videos --skip-photos` specifies that all videos for Alice will be downloaded into the ./videos folder
+- `--use-os-locale` is a global parameter and can be used anywhere
 
 ```{versionadded} 1.32.0
 ```
diff --git a/docs/install.md b/docs/install.md
@@ -7,8 +7,8 @@ There are three ways to run `icloudpd`:
     icloudpd --username your@email.address --directory photos --watch-with-interval 3600
     ```
 
-1. Use package manager to install, update, and, in some cases, run ([Docker](#docker), [PyPI](#pypi), [AUR](#aur), [npm](#npm))
-1. Build and run from the source
+1. Use a package manager to install, update, and, in some cases, run ([Docker](#docker), [PyPI](#pypi), [AUR](#aur), [npm](#npm))
+1. Build and run from source
 
 (docker)=
 ## Docker
@@ -17,9 +17,9 @@ There are three ways to run `icloudpd`:
 docker run -it --rm --name icloudpd -v $(pwd)/Photos:/data -e TZ=America/Los_Angeles icloudpd/icloudpd:latest icloudpd --directory /data --username my@email.address --watch-with-interval 3600
 ```
 
-Image asset date will be converted to specified TZ and then used for creating folders (see [`--folder-structure`](folder-structure-parameter) parameter)
+The image asset date will be converted to the specified TZ and then used for creating folders (see the [`--folder-structure`](folder-structure-parameter) parameter).
 
-Synchronization logic can be adjusted with command-line parameters. Run the following to get full list:
+The synchronization logic can be adjusted with command-line parameters. Run the following to get the full list:
 ``` sh 
 docker run -it --rm icloudpd/icloudpd:latest icloudpd --help
 ``` 
@@ -40,7 +40,7 @@ Getting Docker:
 
 - On Linux, Docker engine and client can be installed using platform package managers, e.g. [Installing on Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-20-04)
 
-- Appliance (e.g. NAS) will have their own way to install Docker engines and running containers - see manufacturer's instructions.
+- Appliances (e.g., NAS) will have their own way to install Docker engines and run containers - see the manufacturer's instructions.
 ```
 
 (pypi)=
@@ -65,7 +65,7 @@ on Windows:
 pip install icloudpd --user
 ```
 
-Plus add `C:\Users\<YourUserAccountHere>\AppData\Roaming\Python\Python<YourPythonVersionHere>\Scripts` to PATH. The exact path will be given at the end of `icloudpd` installation.
+Also add `C:\Users\<YourUserAccountHere>\AppData\Roaming\Python\Python<YourPythonVersionHere>\Scripts` to PATH. The exact path will be given at the end of the `icloudpd` installation.
 ````
 
 ```{note}
@@ -88,7 +88,7 @@ cd icloudpd-bin
 makepkg -sirc
 ```
 
-With the use of the AUR helper e.g. [yay](https://github.com/Jguer/yay) the installation process would look like this:
+With the use of an AUR helper, e.g., [yay](https://github.com/Jguer/yay), the installation process would look like this:
 
 ``` sh
 yay -S icloudpd-bin
@@ -103,17 +103,17 @@ npx --yes icloudpd --directory /data --username my@email.address --watch-with-in
 
 ## macOS binary
 
-`icloudpd` is available as Intel 64bit binary for macOS, but works on ARM macs too (M1, M2, M3).
+`icloudpd` is available as an Intel 64-bit binary for macOS, but works on ARM Macs too (M1, M2, M3).
 
-Here are the steps to make it working:
-- download binary from GitHub [Releases](https://github.com/icloud-photos-downloader/icloud_photos_downloader/releases) into desired local folder
-- add executable flag by running `chmod +x icloudpd-1.32.0-macos-amd64`
-- start it from the terminal: `icloudpd-1.32.0-macos-amd64`
-- Apple will tell you that it cannot check for malicious software and refuse to run the app; click "Ok"
-- Open "System Settings"/"Privacy & Security" and find `icloudpd-1.32.0-macos-amd64` as blocked app; Click "Allow"
+Here are the steps to make it work:
+- Download the binary from GitHub [Releases](https://github.com/icloud-photos-downloader/icloud_photos_downloader/releases) into the desired local folder
+- Add the executable flag by running `chmod +x icloudpd-1.32.0-macos-amd64`
+- Start it from the terminal: `icloudpd-1.32.0-macos-amd64`
+- Apple will tell you that it cannot check for malicious software and refuse to run the app; click "OK"
+- Open "System Settings"/"Privacy & Security" and find `icloudpd-1.32.0-macos-amd64` as a blocked app; click "Allow"
 - Start `icloudpd-1.32.0-macos-amd64` from the terminal again
 - Apple will show another warning; click "Open"
-- After that you can run `icloudpd-1.32.0-macos-amd64 --help` or any other supported command/option
+- After that, you can run `icloudpd-1.32.0-macos-amd64 --help` or any other supported command/option
 
 ## Error on the First Run
 

diff --git a/docs/mode.md b/docs/mode.md
@@ -7,16 +7,16 @@ Added `--delete-after-download` parameter
 `icloudpd` works in one of three modes of operation:
 
 Copy
-:   Download assets from iCloud that are are not in the local storage
+:   Download assets from iCloud that are not in the local storage
 
     This is the default mode
 
 Sync
-:   Download assets from iCloud that are are not in the local storage (same as Copy). In addition, delete local files that were removed in iCloud (moved into "Recently Deleted" album)
+:   Download assets from iCloud that are not in the local storage (same as Copy). In addition, delete local files that were removed in iCloud (moved into the "Recently Deleted" album)
 
     This mode is selected with [`--auto-delete`](auto-delete-parameter) parameter
 
 Move
-:   Download assets from iCloud that are are not in the local storage (same as Copy). Then delete assets in iCloud that are in local storage, optionally leaving recent ones in iCloud
+:   Download assets from iCloud that are not in the local storage (same as Copy). Then delete assets in iCloud that are in local storage, optionally leaving recent ones in iCloud
 
     This mode is selected with [`--keep-icloud-recent-days`](keep-icloud-recent-days-parameter) parameter
diff --git a/docs/naming.md b/docs/naming.md
@@ -41,20 +41,20 @@ LC_ALL=ru_RU.UTF.8 icloudpd --use-os-locale --version
 `--file-match-policy` parameter added and `name-id7` policy implemented
 ```
 
-In large iCloud collections it is possible to have name collisions. To avoid collisions if files need to be downloaded into the same folder, use [`--file-match-policy`](file-match-policy-parameter) parameter:
-- add unique invariant asset identification suffix to the name (e.g. **"IMG_1234_QAZXSW.JPG"**) with `--file-match-policy name-id7`
-- de-duplicate by adding file size as a suffix (e.g. **"IMG_1234-67890.JPG"** for second asset); `--file-match-policy name-size-dedup-with-suffix` - it is default
+In large iCloud collections, it is possible to have name collisions. To avoid collisions if files need to be downloaded into the same folder, use the [`--file-match-policy`](file-match-policy-parameter) parameter:
+- add a unique invariant asset identification suffix to the name (e.g., **"IMG_1234_QAZXSW.JPG"**) with `--file-match-policy name-id7`
+- de-duplicate by adding file size as a suffix (e.g., **"IMG_1234-67890.JPG"** for the second asset); `--file-match-policy name-size-dedup-with-suffix` - this is the default
 
 ## Live Photos
 
 ```{versionchanged} 1.18.0
 `--live-photo-mov-filename-policy` parameter added and `original` policy implemented
 ```
 
-Live Photo assets have two components: still image and short video. `icloudpd` can download both and allows customizing file name of the video portion with [`--live-photo-mov-filename-policy`](live-photo-mov-filename-policy-parameter) parameter:
+Live Photo assets have two components: a still image and a short video. `icloudpd` can download both and allows customizing the file name of the video portion with the [`--live-photo-mov-filename-policy`](live-photo-mov-filename-policy-parameter) parameter:
 
-- Use video file name the same as still image with `original` policy; use `--file-match-policy name-id7` to avoid clashes of video file with other videos.
-- Use suffix from the still image with `suffix` policy: **"IMG_1234_HEVC.MOV"** for **"IMG_1234.HEIC"** still. This is default and works for HEIC still images only
+- Use the same video file name as the still image with the `original` policy; use `--file-match-policy name-id7` to avoid clashes of the video file with other videos.
+- Use a suffix from the still image with the `suffix` policy: **"IMG_1234_HEVC.MOV"** for **"IMG_1234.HEIC"** still image. This is the default and works for HEIC still images only
 
 ## Unicode
 

diff --git a/docs/nas.md b/docs/nas.md
@@ -4,7 +4,7 @@ The following are example setups for NAS.
 
 ## TrueNAS
 
-Use [`Install Custom App` button](https://www.truenas.com/docs/scale/23.10/scaletutorials/apps/usingcustomapp/) to set up `icloudpd`:
+Use the [`Install Custom App` button](https://www.truenas.com/docs/scale/23.10/scaletutorials/apps/usingcustomapp/) to set up `icloudpd`:
 | Field | Value | Note |
 |-------|-------|------|
 Application Name | `icloudpd` |
@@ -22,15 +22,15 @@ Portal Configuration/Protocol to Portal | `HTTP Protocol` |
 Portal Configuration/Use Node IP for Portal IP/Domain | checked | 
 Portal Configuration/Port | `9090` | Same as "Port Forwarding/Host Port" above
 
-Once the app has started, connect to the [WebUI](webui) to enter password and MFA code one of two ways:
-- Using browser from your PC to 9090 port of your NAS
-- Clicking on `icloudpd` button in Detail/Application Info section of TrueNAS portal
+Once the app has started, connect to the [WebUI](webui) to enter the password and MFA code in one of two ways:
+- Using a browser from your PC to port 9090 of your NAS
+- Clicking on the `icloudpd` button in the Detail/Application Info section of the TrueNAS portal
 
 ## Running on Synology NAS
 
-The error `Failed to execv() /tmp/staticx-kJmNbp` has a workaround by (from an SSH terminal in my case) running `sudo mount /tmp -o remount,exec`. [#788](https://github.com/icloud-photos-downloader/icloud_photos_downloader/issues/788)
+The error `Failed to execv() /tmp/staticx-kJmNbp` has a workaround by running `sudo mount /tmp -o remount,exec` (from an SSH terminal). [#788](https://github.com/icloud-photos-downloader/icloud_photos_downloader/issues/788)
 
-CPU/Arch [used by Synology](https://kb.synology.com/en-me/DSM/tutorial/What_kind_of_CPU_does_my_NAS_have) other than amd64 (after x12):
+CPU/Arch [used by Synology](https://kb.synology.com/en-me/DSM/tutorial/What_kind_of_CPU_does_my_NAS_have) other than amd64 (from x12 onwards):
 | Models | CPU | Arch | 
 |-------|-------|------|
 DS124, DS423, DS223j, DS223 | Realtek RTD1619B | arm64 | 
@@ -53,6 +53,6 @@ DS414j | Mindspeed Comcerto C200 | arm32v7
 DS413, DS213+ | Freescale P1022 | power (Unsupported) | 
 DS413j, DS213, DS213air | Marvell Kirkwood 88F6282 | arm32v5 (Unsupported) | 
 
-Non x86 64bit models from x12 and before are not supported
+Non-x86 64-bit models from x12 and earlier are not supported.
 
-[Additional info on Marvel](https://www.kernel.org/doc/html/v6.1/arm/marvell.html)
+[Additional info on Marvell](https://www.kernel.org/doc/html/v6.1/arm/marvell.html)
diff --git a/docs/raw.md b/docs/raw.md
@@ -3,15 +3,15 @@
 ## Apple ProRAW/ProRes
 
 Apple supports shooting stills and videos in [DNG](https://en.wikipedia.org/wiki/Digital_Negative) format and 
-they can be downloaded by `icloudpd` as any other supported format.
+they can be downloaded by `icloudpd` like any other supported format.
 
 ## Imported RAW images
 
 ```{versionadded} 1.19.0
 ```
 
-RAW images from third party cameras can be imported into Apple Photos or uploaded to iCloud.com. 
-These type of assets can also be downloaded by `icloudpd`. The following formats are recognized:
+RAW images from third-party cameras can be imported into Apple Photos or uploaded to iCloud.com. 
+These types of assets can also be downloaded by `icloudpd`. The following formats are recognized:
 
 - Adobe DNG - same as Apple ProRAW
 - Canon CR2, CR3, and CRW
@@ -29,13 +29,13 @@ These type of assets can also be downloaded by `icloudpd`. The following formats
 
 iCloud supports images with two representations. `icloudpd` can download one or both representations.
 
-One representation will be `original` [size](size) and another `alternative`.
+One representation will be the `original` [size](size) and the other `alternative`.
 
-As of June 2024, icloud.com always shows assets with two representations as RAW+JPEG. Photo app on Mac
+As of June 2024, icloud.com always shows assets with two representations as RAW+JPEG. The Photos app on Mac
 allows choosing which representation to treat as original, but it is not clear what that setting changes. 
 
-`icloudpd` disambiguates the behavior with [`--align-raw`](align-raw-parameter) parameter:
+`icloudpd` disambiguates the behavior with the [`--align-raw`](align-raw-parameter) parameter:
 
-- *original* always treat RAW as original [size](size)
-- *alternative* always treat RAW as alternative [size](size)
-- *as-is* treat RAW as it is in iCloud data
+- *original* always treats RAW as the original [size](size)
+- *alternative* always treats RAW as the alternative [size](size)
+- *as-is* treats RAW as it is in iCloud data