Registry / aws / dvc-s3

dvc-s3

JSON →
library3.3.0pypypiunverified

dvc-s3 is a plugin for Data Version Control (DVC) that enables storing and retrieving data, models, and pipelines from Amazon S3. It integrates seamlessly with DVC's CLI and API to manage datasets on S3. The current version is 3.3.0, and it follows a minor release cadence driven by DVC's core development.

pip install dvc dvc-s3
INSTALL
IMPORT
SIG · DVC-S3
D
dvc-s3
awspythonv3.3.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart demonstrates how to initialize a DVC project, configure an S3 remote, add a data file to DVC, and push it to your S3 bucket. Ensure you have `dvc` and `dvc-s3` installed, and your AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) and desired S3 bucket name (DVC_S3_BUCKET) are set as environment variables.

import os import subprocess import shutil # Ensure dvc and dvc-s3 are installed: `pip install dvc dvc-s3` # --- Configuration for S3 (replace with your actual details) --- # For this example to work with a real S3 bucket, you need valid AWS credentials # and an S3 bucket. It's recommended to set them as environment variables: # export AWS_ACCESS_KEY_ID='AKIA...' # export AWS_SECRET_ACCESS_KEY='YOUR_SECRET_KEY' # export DVC_S3_BUCKET='your-dvc-test-bucket-name' # export AWS_DEFAULT_REGION='us-east-1' aws_access_key_id = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_AWS_ACCESS_KEY_ID_PLACEHOLDER') aws_secret_access_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_AWS_SECRET_ACCESS_KEY_PLACEHOLDER') s3_bucket_name = os.environ.get('DVC_S3_BUCKET', 'your-dvc-test-bucket-name') s3_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1') if 'YOUR_AWS_ACCESS_KEY_ID_PLACEHOLDER' in aws_access_key_id or 'your-dvc-test-bucket-name' in s3_bucket_name: print("\nWARNING: Please set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, DVC_S3_BUCKET, and AWS_DEFAULT_REGION environment variables for the quickstart to interact with real S3.") print("Proceeding with placeholder values, push will likely fail.") project_dir = "dvc-s3-quickstart" # Clean up previous runs if any (optional, uncomment if needed for repeated runs) # if os.path.exists(project_dir): # shutil.rmtree(project_dir) os.makedirs(project_dir, exist_ok=True) os.chdir(project_dir) try: # 1. Initialize DVC repository (without Git for simplicity) print("\n1. Initializing DVC repository...") subprocess.run(["dvc", "init", "--no-scm"], check=True) # 2. Create a dummy data directory and file os.makedirs("data", exist_ok=True) with open("data/my_data.txt", "w") as f: f.write("Hello, DVC and S3!") # 3. Add S3 remote print(f"\n3. Adding S3 remote 'my_s3_remote' to s3://{s3_bucket_name}/dvc-store") subprocess.run(["dvc", "remote", "add", "-d", "my_s3_remote", f"s3://{s3_bucket_name}/dvc-store"], check=True) subprocess.run(["dvc", "remote", "modify", "my_s3_remote", "region", s3_region], check=True) # 4. Add data to DVC print("\n4. Adding 'data/my_data.txt' to DVC...") subprocess.run(["dvc", "add", "data/my_data.txt"], check=True) # 5. Push data to the S3 remote print("\n5. Pushing data to S3 remote...") subprocess.run(["dvc", "push"], check=True) print("\nQuickstart completed! Check your S3 bucket for the DVC store.") except subprocess.CalledProcessError as e: print(f"\nERROR: DVC command failed.\nCommand: {' '.join(e.cmd)}\nOutput:\n{e.stdout.decode()}\n{e.stderr.decode()}") print("Please ensure DVC and dvc-s3 are installed, AWS credentials are set, and the S3 bucket exists and is writable.") except FileNotFoundError: print("ERROR: 'dvc' command not found. Please ensure DVC is installed and in your PATH.") finally: os.chdir("..") # Return to original directory # Optional: Clean up the created project directory # shutil.rmtree(project_dir)
dvc --version
Debug
Known issues
breakingThe `boto3` library is no longer a direct dependency as of version 3.3.0. If your project implicitly relied on `boto3` being installed alongside `dvc-s3` for other S3-related operations, you will now need to install it explicitly (e.g., `pip install boto3`).
fix
If you need `boto3` for other reasons in your environment, install it separately: `pip install boto3`.
affects: >=3.3.0
gotchaThe `dvc-s3` plugin must be installed separately from `dvc`. Installing just `dvc` will not provide S3 remote support. Always use `pip install dvc dvc-s3` to ensure S3 functionality.
fix
Always install `dvc-s3` alongside `dvc` using `pip install dvc dvc-s3` to ensure the S3 remote is available.
affects: All versions
gotchaAWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) and S3 bucket configuration are crucial. Incorrectly set credentials or a non-existent/inaccessible bucket are common causes of errors when attempting to access S3 remotes.
fix
Ensure AWS credentials are correctly configured via environment variables, AWS shared credentials file, or IAM roles. Verify the S3 bucket exists and DVC has appropriate permissions (read/write access).
affects: All versions
breakingVersion 3.2.1 and later require `s3fs>=2024.12.0`. If you are running an older version of `s3fs`, you must upgrade to ensure compatibility and stability when using `dvc-s3`.
fix
Upgrade `s3fs` by running `pip install --upgrade s3fs`.
affects: >=3.2.1
gotchaExplicitly setting the S3 region for your remote is often good practice to avoid ambiguity or issues with AWS endpoint resolution, especially when working across different regions or with specific AWS configurations.
fix
After adding your remote, use `dvc remote modify <remote_name> region <your_region>` (e.g., `dvc remote modify my_s3_remote region us-east-1`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'boto3'
The 'boto3' library, required for DVC's S3 functionality, is not installed.
fix
Install 'boto3' using pip: 'pip install boto3'.
ERROR: failed to pull data from the cloud
The data has not been pushed to the DVC remote, or there is a mismatch between the Git repository and the DVC cache.
fix
Ensure that 'dvc push' has been executed from the original project, and try 'dvc pull' again.
AttributeError: 'S3File' object has no attribute 'getvalue'
The 'S3File' object does not support the 'getvalue()' method, which is being called in the code.
fix
Modify the code to avoid calling 'getvalue()' on 'S3File' objects, or use a different method to retrieve the file content.
WARNING: Cache 'xxxx' not found.
The specified cache file is missing, possibly due to it not being pushed to the DVC remote.
fix
Run 'dvc push' to upload the cache to the remote, then try 'dvc pull' again.
[Errno 24] Too many open files
The system has reached the limit of open file descriptors, often due to high parallelism in DVC operations.
fix
Increase the open file descriptors limit using 'ulimit -n 1024' on UNIX-like systems, or reduce the number of parallel jobs in DVC commands.
Upgrade
Version history
3.3.0latest on PyPI · released Jan 16, 2026
Audit
Dependencies
dvcrequiredThis is a plugin for DVC; DVC must be installed separately to use dvc-s3 functionality.
s3fsrequiredProvides the underlying filesystem interface for S3 storage. Minimum version >=2024.12.0 required since v3.2.1.
boto3optionalWas a transitive dependency through s3fs but explicitly dropped in v3.3.0. May still be needed if your project implicitly relied on it or requires it for other S3 operations.
Agent activity
27 hits · last 30 days
node
22
OpenAI (training)
1
Resources
dvc-s3 — pip install dvc-s3 · libregistry