{"id":7659,"library":"rclone-python","title":"rclone-python","description":"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.","status":"active","version":"0.1.24","language":"en","source_language":"en","source_url":"https://github.com/Johannes11833/rclone_python","tags":["rclone","cloud storage","file transfer","sync","wrapper","cli"],"install":[{"cmd":"pip install rclone-python","lang":"bash","label":"Install rclone-python"}],"dependencies":[],"imports":[{"symbol":"rclone","correct":"from rclone_python import rclone"},{"note":"Needed for creating new rclone remote connections.","symbol":"RemoteTypes","correct":"from rclone_python.remote_types import RemoteTypes"}],"quickstart":{"code":"from rclone_python import rclone\nfrom rclone_python.remote_types import RemoteTypes\nimport os\n\n# Ensure rclone binary is installed and in PATH\nif not rclone.is_installed():\n    print(\"rclone CLI tool is not installed or not found in PATH.\")\n    print(\"Please install rclone: https://rclone.org/install/\")\n    exit(1)\n\nprint(f\"rclone is installed: {rclone.is_installed()}\")\nprint(f\"rclone version: {rclone.version()['rclone_version']}\")\n\n# Example: Create a dummy local remote for demonstration\n# In a real scenario, you'd configure a cloud remote.\n# This assumes a 'local' type remote, no sensitive data.\n# For actual cloud remotes, you would provide client_id, client_secret, etc.\n# You might also use rclone.with_config(config_string) for in-memory config.\n\n# Ensure a 'test_data' directory exists locally for the example\nos.makedirs('./test_data', exist_ok=True)\nwith open('./test_data/hello.txt', 'w') as f:\n    f.write('Hello, rclone-python!')\n\n# A simple rclone copy operation\n# Source: a local path, Destination: a local path (acting as a remote)\ntry:\n    # This 'local_test' remote is created dynamically for the example.\n    # For persistent remotes, use 'rclone config' or rclone.create_remote() once.\n    # For this example, we'll use a direct path as 'remote'.\n    # The rclone_python library primarily interfaces with the configured rclone remotes.\n    # To simulate copying to a 'remote' which is just another local folder:\n    # Create a destination folder that acts as our 'remote target'\n    dest_path = './rclone_dest'\n    os.makedirs(dest_path, exist_ok=True)\n    print(f\"\\nCopying './test_data/hello.txt' to '{dest_path}'...\")\n    rclone.copy('./test_data', dest_path)\n    print(\"Copy complete.\")\n\n    # List contents of the destination\n    print(f\"\\nContents of '{dest_path}':\")\n    for item in rclone.ls(dest_path):\n        print(f\"- {item['Path']} (size: {item['Size']} bytes)\")\n\nexcept rclone.RcloneException as e:\n    print(f\"Rclone command failed: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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`."},"warnings":[{"fix":"Install the rclone CLI tool according to its official documentation (https://rclone.org/install/) for your operating system.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"<0.1.18"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.1.22"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.1.20"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"rclone CLI tool is not installed or not found in PATH."},{"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+).","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.","error":"Rclone command failed: failed to load config file ... process cannot access the file because its being used by other process"},{"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.","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.","error":"Rclone command failed: Failed to copy: object not found"},{"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.","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.","error":"Rclone command failed: (empty error message during transfer failure)"}]}