Install and Use alist-sync to Copy Files

2 min
Notes

alist-sync is a Python tool for copying files between AList storage locations. The project is still at an early stage, so commands and configuration may change. Read the current README and configuration template before using it. This article explains why I wanted it and how to get started using the repository’s current instructions.

Why I wanted it

I have files that I periodically upload to cloud storage as an off-device backup. The collection grows over time, but most files do not change after they are uploaded.

The OneDrive desktop client used a lot of CPU on my computer, so I wanted a lighter way to copy local files to OneDrive. Since I already had OneDrive mounted in AList, I tried using alist-sync to copy a local directory to that AList storage.

Install

The project requires Python 3.10 or newer and Git. A virtual environment keeps its Python dependencies separate from the system installation:

git clone https://github.com/lee-cq/alist-sync.git
cd alist-sync
python3 -m venv .venv
source .venv/bin/activate
bash ./bootstrap.sh install

On Windows, use Git Bash or WSL for the Bash commands. Check the repository’s current instructions if the bootstrap process changes.

Configure and run

Copy the configuration template and restrict access to the file, since it may contain credentials:

cp config-template.yaml config.yaml
chmod 600 config.yaml

Edit config.yaml with your AList server, storage, and source/destination paths. Inspect the template carefully and replace any example credentials. Do not commit a configuration file containing secrets to a public repository.

The project’s current README gives this Linux command to start the configured task:

./bootstrap.sh main sync

Use the current config-template.yaml as the reference for configuration fields. The README describes copy as implemented: it skips files that already exist at the destination and does not delete files that exist only at the destination. Mirror deletion and multi-source synchronization are still listed as in progress or planned. Test the configuration with a small set of recoverable files before relying on it for important data.