Skip to main content

synology drive api python wrapper

Project description

Synology Drive API

Downloads Python License Contributions welcome

synology-drive-api is inspired by synology-api. This repo is aimed at providing Synology drive api wrapper and related helper functions. It helps you manage your files/folders/labels in synology drive. By means of Synology Office, you can edit spreadsheet on Drive and use this api wrapper read spreadsheet. It supports Python 3.7+.


pip install synology-drive-api

Get login session

You can access drive by IP, drive domain or nas domain + drive path.

Synology Drive allows same user with multiple login session. if you need multiple login session and label functions, disable label cache.

from import SynologyDrive

# default http port is 5000, https is 5001. 
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP) as synd:
# Use specified port
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, NAS_PORT) as synd:
# use http instead of https. https: default is True.
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, https=False) as synd:
# use domain name or name + path access drive
# Enabled in Application Portal | Application | Drive | General | Enable customized alias
drive_path_demo = 'your_nas_domain/drive'
# Enabled in Application Portal | Application | Drive | General | Enable customized domain
drive_path_demo2 = 'your_drive_domain'
with SynologyDrive(NAS_USER, NAS_PASS, drive_path_demo) as synd:
# disable label cache
with SynologyDrive(NAS_USER, NAS_PASS, drive_path_demo, enable_label_cache=False) as synd:

If you use dsm 7, default dsm_version is '6'.

from import SynologyDrive

# default http port is 5000, https is 5001. 
with SynologyDrive(NAS_USER, NAS_PASS, NAS_IP, dsm_version='7') as synd:

Manage labels

Synology drive thinks labels need to belong to single user. If you want share labels between users, you should have access to these user accounts. Another solution is creating a tool user.

Synology drive search function provide label union search rather than intersection search. If you need label intersection search, combine them into one label.

Get label info

# get single label info
# get all labels info

Create/delete label

Label name is unique in drive.

# create a label, color name: gray/red/orange/yellow/green/blue/purple.
# default color is gray, default position is end of labels. 0 is first position.
ret = synd.create_label('your_label_name', color='orange', pos=0)
# delete label by name/id.
ret = synd.delete_label('your_label_name')
ret = synd.delete_label(label_id=419)

Add/delete path label

# acition:add, delete
synd.manage_path_label(action, path, label)

path examples:

1. '/team-folders/test_drive/SCU285/test.xls', '/mydrive/test_sheet_file.osheet'
2. '505415003021516807'
3. ['505415003021516807', '505415003021516817']
4. ["id:505415003021516807", "id:525657984139799470", "id:525657984810888112"]
5. ['/team-folders/test_drive/SCU285/test.xls', '/team-folders/test_drive/SCU283/test2.xls']

label examples:

1. 'label_name'
2. ['label_name_1', 'lable_name_2']
3. [{"action": "add", "label_id": "15"}, {"action": "add", "label_id": "16"}]

List labelled files

Filter files or folders by single label. If you want to use label union search, use search functions (todo).


Manage File/Folder

Team folder start with /team-folders/, Private folder start with /mydrive/

List TeamFolder

Teamfolder is virtual parent folder of shared folders in Synology drive. When you login in Drive, you can see your authorized shared folder.

# {sub_folder_name: folder_id, ...}

List Folder

List Folder or files info of a folder


Get specific folder or file info

Get folder or file info such as created time.

# file_path or file_id "552146100935505098"

Create Folder

# create folder in your private folder
# create folder in dest folder
synd.create_folder('test', 'team-folder/folder2/')

Upload file

You don't need create folder subfolder before uploading your file.

# prepare your file
file = io.BytesIO(mail_attachment['file'])
# add a file name to file = strip_file_name(mail_attachment['name'])
ret_upload = nas_client.upload_file(file, dest_folder_path=dest_folder_path)
# upload to your private folder
ret_upload = nas_client.upload_file(file)

You can upload xlsx or docx as synology office file.

with open('test.xlsx', 'rb') as file:
    nas_client.upload_as_synology_office_file(file, '/mydrive/')

Download file

New: Support osheet and odoc extensions.

file_name = 'test.osheet'
bio = synd.download_file(f'/mydrive/{file_name}')
with open(file_name, 'wb') as f:

Download Synology office file

import pandas as pd

# download osheet as xlsx and read into pandas dataframe.
bio = synd.download_synology_office_file('/mydrive/test.osheet')
pd.read_excel(bio, sheet_name=None)

# dowloand odoc as docx
bio = synd.download_synology_office_file('/mydrive/test.odoc')
with open('test.docx', 'wb') as f:

Delete file or folder

Delete file or folder is an async task.


Rename file or folder

# Rename file '/mydrive/H3_AP201812091265503218_1.pdf' to '/mydrive/new.pdf'
synd.rename_path('new.pdf', '/mydrive/H3_AP201812091265503218_1.pdf')
# Rename folder '/mydrive/test_folder' to '/mydrive/abc_folder'
synd.rename_path('abc_folder', '/mydrive/test_folder')

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

synology_drive_api-1.0.6.tar.gz (14.7 kB view hashes)

Uploaded source

Built Distribution

synology_drive_api-1.0.6-py3-none-any.whl (14.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page