rclone-python

Common errors

• rclone CLI tool is not installed or not found in PATH.

  cause 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

  cause 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

  cause 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)

  cause 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.

Warnings

• breaking The `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.
• breaking As 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.
• gotcha The 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.
• gotcha Before 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.

Install

• pip install rclone-python Install rclone-python

Imports

• rclone

  from rclone_python import rclone

• RemoteTypes

  from rclone_python.remote_types import RemoteTypes

  Needed for creating new rclone remote connections.

Quickstart

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}")