Registry / aws / rclone-python

rclone-python

JSON →
library0.1.24pypypi✓ verified 85d ago

rclone-python is a Python wrapper for the powerful rclone command-line tool, enabling programmatic interaction with various cloud storage providers. It provides a Pythonic interface for operations like copying, moving, syncing, listing, and managing files and remotes. The library is actively maintained, currently at version 0.1.24, and receives regular updates, often with minor bug fixes and feature enhancements.

pip install rclone-python
INSTALL
IMPORT
SIG · RCLONE-PYTHON
R
rclone-python
awspythonv0.1.24
Install
2.8s avg
Import
187ms
Disk
29MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.24 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.196s · 30.1MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.8s · import 0.177s · 31MB
29MB installed
● package 29MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

rclone
from rclone_python import rclone
RemoteTypes
from rclone_python.remote_types import RemoteTypes
Needed for creating new rclone remote connections.

This quickstart demonstrates how to import and use the `rclone_python` library. It includes checking for the rclone binary, performing a simple file copy operation, and listing the contents of a directory. It also shows basic error handling for `RcloneException`.

from rclone_python import rclone from rclone_python.remote_types import RemoteTypes import os # Ensure rclone binary is installed and in PATH if not rclone.is_installed(): print("rclone CLI tool is not installed or not found in PATH.") print("Please install rclone: https://rclone.org/install/") exit(1) print(f"rclone is installed: {rclone.is_installed()}") print(f"rclone version: {rclone.version()['rclone_version']}") # Example: Create a dummy local remote for demonstration # In a real scenario, you'd configure a cloud remote. # This assumes a 'local' type remote, no sensitive data. # For actual cloud remotes, you would provide client_id, client_secret, etc. # You might also use rclone.with_config(config_string) for in-memory config. # Ensure a 'test_data' directory exists locally for the example os.makedirs('./test_data', exist_ok=True) with open('./test_data/hello.txt', 'w') as f: f.write('Hello, rclone-python!') # A simple rclone copy operation # Source: a local path, Destination: a local path (acting as a remote) try: # This 'local_test' remote is created dynamically for the example. # For persistent remotes, use 'rclone config' or rclone.create_remote() once. # For this example, we'll use a direct path as 'remote'. # The rclone_python library primarily interfaces with the configured rclone remotes. # To simulate copying to a 'remote' which is just another local folder: # Create a destination folder that acts as our 'remote target' dest_path = './rclone_dest' os.makedirs(dest_path, exist_ok=True) print(f"\nCopying './test_data/hello.txt' to '{dest_path}'...") rclone.copy('./test_data', dest_path) print("Copy complete.") # List contents of the destination print(f"\nContents of '{dest_path}':") for item in rclone.ls(dest_path): print(f"- {item['Path']} (size: {item['Size']} bytes)") except rclone.RcloneException as e: print(f"Rclone command failed: {e}") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe `rclone_python` library is a wrapper for the `rclone` CLI tool. The `rclone` binary itself MUST be installed separately on the system and be discoverable in the system's PATH for the Python wrapper to function. The Python package does NOT bundle the rclone binary.
fix
Install the rclone CLI tool according to its official documentation (https://rclone.org/install/) for your operating system.
affects: All versions
breakingAs of v0.1.18 and v0.1.19, `RcloneException` is consistently raised whenever an underlying rclone command fails. Previous versions might have returned non-zero exit codes or empty error messages without raising a dedicated exception.
fix
Update your code to include `try...except rclone.RcloneException as e:` blocks for robust error handling. The exception object contains `output` (a dictionary) and `status` (an integer) attributes for detailed error information.
affects: <0.1.18
gotchaThe default behavior for rclone's configuration file location might not always be suitable, especially in containerized or specific deployment environments. Prior to v0.1.22, explicitly managing the config path was less streamlined.
fix
Utilize the support for custom rclone config paths introduced in v0.1.22. You can specify the `--config` flag via `extra_args` or investigate if the wrapper offers a direct parameter for it. Alternatively, set the `RCLONE_CONFIG` environment variable to point to your desired configuration file.
affects: <0.1.22
gotchaBefore version 0.1.20, all log output from rclone operations, including normal informational messages, were redirected to `stderr` by default. This could make parsing standard output or distinguishing error logs difficult.
fix
Upgrade to `rclone-python` v0.1.20 or later. This version fixed the redirection issue, ensuring logs are routed appropriately. If on older versions, be mindful when parsing `stderr` output.
affects: <0.1.20
Errors
Common errors & fixes
rclone CLI tool is not installed or not found in PATH.
The rclone command-line executable is not installed on the system, or its location is not included in the system's PATH environment variable.
fix
Install the `rclone` CLI tool from its official website (https://rclone.org/install/) and ensure its executable is in a directory listed in your system's PATH. On Linux/macOS, this often means placing it in `/usr/local/bin`.
Rclone command failed: failed to load config file ... process cannot access the file because its being used by other process
Rclone could not access its configuration file (`rclone.conf`). This can happen if the path to the config file is incorrect, or if another process has an exclusive lock on the file.
fix
Verify that the `rclone.conf` file exists at the expected location (default is `~/.config/rclone/rclone.conf` on Linux/macOS, or `%APPDATA%\rclone\rclone.conf` on Windows), and that your Python process has read/write permissions. If running multiple rclone instances, ensure they don't contend for the same config file. Consider using `rclone.with_config()` for in-memory configuration or a custom config path (v0.1.22+).
Rclone command failed: Failed to copy: object not found
During a copy or move operation, rclone could not locate the source object or resolve the destination path. This can be due to incorrect remote names, typos in paths, or issues with the remote itself.
fix
Double-check the source and destination paths, including remote names (e.g., `remote_name:path/to/file`). Ensure the remote is correctly configured and accessible. Verify that the specified source file or directory actually exists on the remote or local filesystem.
Rclone command failed: (empty error message during transfer failure)
Prior to v0.1.23, some failed transfer operations resulted in empty or uninformative error messages from the rclone-python wrapper, making debugging difficult.
fix
Upgrade `rclone-python` to version 0.1.23 or newer. This version specifically addresses the bug where empty error messages were returned during failed transfer operations, providing more actionable feedback.
Upgrade
Version history
0.1.24latest on PyPI · released Jan 26, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
99 hits · last 30 days
node
94
OpenAI (training)
1
Resources
rclone-python — pip install rclone-python · libregistry