{"id":9348,"library":"sysrsync","title":"sysrsync: Python wrapper for rsync","description":"sysrsync is a simple and safe Python wrapper designed to execute the system's `rsync` command-line utility. It provides a programmatic interface to construct `rsync` commands, helping to prevent common shell injection vulnerabilities and simplify complex `rsync` operations. The current version is 1.1.1, and it maintains an active but infrequent release cadence, primarily for bug fixes and minor enhancements.","status":"active","version":"1.1.1","language":"en","source_language":"en","source_url":"https://github.com/gchamon/sysrsync","tags":["rsync","shell","subprocess","cli","synchronization","file transfer"],"install":[{"cmd":"pip install sysrsync","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary interaction is via the top-level 'run' function, not an instantiated class.","wrong":"from sysrsync import SysRsync","symbol":"run","correct":"import sysrsync\nresult = sysrsync.run(...)"}],"quickstart":{"code":"import sysrsync\nimport os\n\n# Create dummy files for demonstration\nif not os.path.exists(\"my_source_folder\"): os.makedirs(\"my_source_folder\")\nwith open(\"my_source_folder/file1.txt\", \"w\") as f: f.write(\"Hello\")\nwith open(\"my_source_folder/file2.txt\", \"w\") as f: f.write(\"World\")\n\n# Example: Local to Local sync (replace with your actual paths)\n# This requires rsync to be installed on your system.\n# In a real scenario, 'destination_ssh_user' and 'destination_ssh_host' would be used for remote sync.\nprint(\"Attempting local sync...\")\ntry:\n    result = sysrsync.run(\n        source=\"my_source_folder/\", # Trailing slash means copy contents of folder\n        destination=\"./my_destination_folder/\",\n        options=[\"-a\", \"--delete\", \"-v\"],\n        sync=True # Wait for completion\n    )\n    print(f\"Rsync completed with exit code: {result.returncode}\")\n    print(f\"STDOUT:\\n{result.stdout.decode()}\")\n    if result.stderr: print(f\"STDERR:\\n{result.stderr.decode()}\")\nexcept sysrsync.exceptions.SysrsyncError as e:\n    print(f\"Rsync failed: {e}\")\n    print(f\"STDOUT:\\n{e.result.stdout.decode()}\")\n    if e.result.stderr: print(f\"STDERR:\\n{e.result.stderr.decode()}\")\n\n# Clean up dummy files\nimport shutil\nif os.path.exists(\"my_source_folder\"): shutil.rmtree(\"my_source_folder\")\nif os.path.exists(\"my_destination_folder\"): shutil.rmtree(\"my_destination_folder\")","lang":"python","description":"This quickstart demonstrates how to perform a local file synchronization using `sysrsync.run`. It uses the `source` and `destination` arguments, along with standard `rsync` options. The `sync=True` argument ensures the function waits for the `rsync` process to complete and returns a `subprocess.CompletedProcess` object. It also includes basic error handling for `sysrsync.exceptions.SysrsyncError`."},"warnings":[{"fix":"Upgrade to `sysrsync` version 1.1.1 or newer to benefit from the bug fix for strict host checking issues.","message":"Prior to version 1.1.1, `sysrsync` had a bug that could lead to false strict host checking errors or unexpected SSH connection failures when using remote destinations. This often required manual intervention or workarounds.","severity":"gotcha","affected_versions":"<1.1.1"},{"fix":"Ensure `rsync` is installed on your operating system (e.g., `sudo apt-get install rsync` on Debian/Ubuntu, `brew install rsync` on macOS) and accessible via your system's PATH.","message":"The `sysrsync` library is a wrapper around the system's `rsync` command. If `rsync` is not installed or not in your system's PATH, `sysrsync` calls will fail with an OS-level error indicating the command cannot be found.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If your application relied on `sysrsync` to implicitly verify remote source existence, you will need to add explicit checks in your code before calling `sysrsync.run` when upgrading from versions older than 0.3.0.","message":"In version 0.3.0, the functionality that checks if the remote source exists was disabled. This means `sysrsync` no longer performs an implicit check for remote source existence before initiating the `rsync` transfer.","severity":"breaking","affected_versions":">=0.3.0 (behavioral change from <0.3.0)"},{"fix":"Always be explicit with trailing slashes in your `source` and `destination` paths based on whether you want to copy the folder's contents or the folder itself.","message":"Understanding `rsync`'s trailing slash behavior is critical. A trailing slash on the source path (`source=\"folder/\"`) copies the *contents* of the folder, while no trailing slash (`source=\"folder\"`) copies the folder itself into the destination. Misunderstanding this is a common source of unexpected sync results.","severity":"gotcha","affected_versions":"All versions (inherent `rsync` behavior)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `rsync` on your operating system (e.g., `sudo apt-get install rsync` or `brew install rsync`) and verify it's accessible from your shell.","cause":"The `rsync` command-line utility was not found in the system's PATH.","error":"sysrsync.exceptions.SysrsyncError: rsync command failed with exit code 127"},{"fix":"Check your SSH configuration, ensure the `destination_ssh_user` has proper SSH keys or passwordless access, verify `destination_ssh_host` is reachable, and confirm firewall rules. Inspect the `stderr` output from the exception for more specific SSH messages.","cause":"A generic SSH error, often related to authentication failure, hostname resolution, or network connectivity when syncing to a remote destination.","error":"sysrsync.exceptions.SysrsyncError: rsync command failed with exit code 255"},{"fix":"Examine the `stderr` output from the `SysrsyncError` exception. It will usually contain specific `rsync` messages indicating which file failed to transfer and why (e.g., 'Permission denied', 'No such file or directory', 'No space left on device'). Adjust permissions, free up space, or correct paths accordingly.","cause":"Partial transfer due to an error. This often indicates issues with permissions, disk space, or a file/directory not found on the source or destination.","error":"sysrsync.exceptions.SysrsyncError: rsync command failed with exit code 23"}]}