Install and Setup OneDrive Client in a Headless Debian Server

Page content

There is still no official OneDrive client for Linux, the project “OneDrive Client for Linux” is the only choice. It provides a powerful and highly configurable client can run on all major Linux distributions, FreeBSD, or as a Docker container. It supports one-way and two-way sync capabilities and securely connects to Microsoft OneDrive services.

This post is the workthrough of installation and configuration of OneDrive Linux ina headless Debian bullseye/11 server.

I am working on a server with Debian bullseye/11, kernel version 5.11 x86_64.

1. Installation

Note: Deprecated

It is quiet easy to install OneDrive Client in Debian:

$ sudo apt update
$ sudo apt install onedrive

According to the OneDrive Client for Linux Documentation, it is Not recommended to install OneDrive Client from Debian Package Repositories.

The recommended way is to install from OpenSuse Build Servicei according to the Instructions.

Step 1: Add the OpenSuSE Build Service repository release key

Add the OpenSuSE Build Service repository release key using the following command:

$ wget -qO - | gpg --dearmor | sudo tee /usr/share/keyrings/obs-onedrive.gpg > /dev/null

Step 2: Add the OpenSuSE Build Service repository

Add the OpenSuSE Build Service repository using the following command:

$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/obs-onedrive.gpg] ./" | sudo tee /etc/apt/sources.list.d/onedrive.list

Step 3: Update your apt package cache


$ sudo apt update

Step 4: Install ‘onedrive’


sudo apt install --no-install-recommends --no-install-suggests onedrive

Step 5: Read ‘Known Issues’ with these packages

Read and understand the known issues with these packages below, taking any action that is needed.

If you’d like to build from source, please read the document.

2. Authorize the application with your OneDrive Account

authorization of the application with your OneDrive Account is necessary. Simply run the application without any command switches:

$ onedrive

You will be asked to open a specific URL by using your web browser where you will have to login into your Microsoft Account and give the application the permission to access your files. After giving permission to the application, you will be redirected to a blank page. Copy the URI of the blank page into the application.

$ onedrive
Configuring Global Azure AD Endpoints
Authorize this app visiting:

Enter the response uri:

Application has been successfully authorised, however no additional command switches were provided.

Please use --help for further assistance in regards to running this application.

3. Configuration

3.1 Display current configuration

$ onedrive --display-config


onedrive version                       = v2.4.10-1
Config path                            = /home/user/.config/onedrive
Config file found in config path       = false
Config option 'check_nosync'           = false
Config option 'sync_dir'               = /home/user/OneDrive
Config option 'skip_dir'               = 
Config option 'skip_file'              = ~*|.~*|*.tmp
Config option 'skip_dotfiles'          = false
Config option 'skip_symlinks'          = false
Config option 'monitor_interval'       = 300
Config option 'min_notify_changes'     = 5
Config option 'log_dir'                = /var/log/onedrive/
Config option 'classify_as_big_delete' = 1000
Config option 'upload_only'            = false
Config option 'no_remote_delete'       = false
Config option 'remove_source_files'    = false
Config option 'sync_root_files'        = false
Selective sync 'sync_list' configured  = false
Business Shared Folders configured     = false

3.2 Customize configuration

The config file does not get created by default, and should only be created if you want to change the default operational parameters.

Valid directories for the config file are:

# or

For Debian bullseye/11, the config file template is located at:


So, you need to do:

$ mkdir -p ~/.config/onedrive
cp /usr/share/doc/onedrive/config ~/.config/onedrive/config

Please note, the latest OneDrive Client version is 2.4.15, whereas in Debian bullseye/11, it is 2.4.10. So there are slightly difference between these two versions.

$ cat /usr/share/doc/onedrive/config
# Configuration for OneDrive Linux Client
# This file contains the list of supported configuration fields
# with their default values.
# All values need to be enclosed in quotes
# When changing a config option below, remove the '#' from the start of the line
# For explanations of all config options below see docs/ or the man page.
# sync_dir = "~/OneDrive"
# skip_file = "~*|.~*|*.tmp"
# monitor_interval = "300"
# skip_dir = ""
# log_dir = "/var/log/onedrive/"
# drive_id = ""
# upload_only = "false"
# check_nomount = "false"
# check_nosync = "false"
# download_only = "false"
# disable_notifications = "false"
# disable_upload_validation = "false"
# enable_logging = "false"
# force_http_11 = "false"
# force_http_2 = "false"
# local_first = "false"
# no_remote_delete = "false"
# skip_symlinks = "false"
# debug_https = "false"
# skip_dotfiles = "false"
# dry_run = "false"
# min_notify_changes = "5"
# monitor_log_frequency = "5"
# monitor_fullscan_frequency = "10"
# sync_root_files = "false"
# classify_as_big_delete = "1000"
# user_agent = ""
# remove_source_files = "false"
# skip_dir_strict_match = "false"
# application_id = ""
# resync = "false"
# bypass_data_preservation = "false"
# azure_ad_endpoint = ""
# azure_tenant_id = "common"
# sync_business_shared_folders = "false"
# sync_dir_permissions = "700"
# sync_file_permissions = "600"
# rate_limit = "131072"

The config file for 2.4.15 can be viewed at here.

3.3 Some common used configuration settings

Most command line options have a respective configuration file setting.

3.3.1 OneDrive root dir

  • Param: sync_dir
  • Default: sync_dir = "~/OneDrive"
  • Note:
    • After changing sync_dir, you must perform a full re-synchronization by adding --resync to your existing command line - for example:
$ onedrive --synchronize --resync
  • Directory and file permissions:
    • Directories: 0700, or drwx------
    • Files: 0600, or -rw-------
    • Important: Special permission bits (setuid, setgid, sticky bit) are not supported.

3.3.2 Skip some files

  • Param: skip_file
  • Default: skip_file = "~*|.~*|*.tmp"
  • Note:
    • Patterns are case insensitive.
    • * and ? wildcards characters are supported.
    • Use | to separate multiple patterns.
    • Important: Do not use a skip_file entry of .* as this will prevent correct searching of local changes to process.

3.3.3 Skip dot files

  • Param: skip_dotfiles
  • Default: skip_dotfiles = "false"
  • Param: skip_symlinks
  • Default: skip_symlinks = "false"

3.3.5 Limit internet bandwith usage

  • Param: rate_limit
  • Default: rate_limit = "131072"
  • Valid rate limit values:
Value Speed Note
131072 128 KB/s minimum for basic application operations to prevent timeouts
262144 256 KB/s
524288 512 KB/s
1048576 1 MB/s
10485760 10 MB/s
104857600 100 MB/s

3.3.6 Disable notification

  • Param: disable_notifications
  • Default: disable_notifications = "false"
  • For a headless server, it was set to true.

3.3.7 Timeout for a file operation

Operation Timeout is the maximum amount of time (seconds) a file operation is allowed to take. This includes DNS resolution, connecting, data transfer, etc.

  • Param: operation_timeout
  • Default: operation_timeout = "3600"

4. Test the configuration

You can test your configuration by utilising the --dry-run CLI option, no changes will be applied.

$ onedrive --synchronize --verbose --dry-run
DRY-RUN Configured. Output below shows what 'would' have occurred.
Loading config ...
Using Config Dir: /home/user/.config/onedrive
Initializing the OneDrive API ...
Opening the item database ...
All operations will be performed in: /home/user/OneDrive
Initializing the Synchronization Engine ...
Account Type: personal

5. Performing a sync

Simply running:

$ onedrive --synchronize

6. Run onedrive as a non-root user via systemd in Debian

$ systemctl --user enable onedrive
$ systemctl --user start onedrive

NOTE: For other Linux distributions, please visit document.

A. Reference

  1. OneDrive client for Linux github page
  2. Configuration and Usage of the OneDrive Free Client