awscurl

library0.39pypypiunverified

AWSCurl is a command-line tool and Python module that provides a curl-like interface for making authenticated requests to AWS APIs. It simplifies interaction with AWS services by automatically handling AWS Signature Version 4 request signing, credential lookup, and header construction. The library supports all AWS services that utilize SigV4, including S3, CloudFront, and Lambda. Currently at version 0.39, it maintains an active release cadence with multiple updates throughout the year to introduce features and address bugs.

aws http-networking

pip install awscurl

github ↗package ↗

INSTALL

IMPORT

SIG · AWSCURL

awscurl

awspythonv0.39

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Make an authenticated GET request to list the contents of an S3 bucket. Ensure your AWS credentials are configured via environment variables, an AWS CLI profile, or provided directly via CLI flags.

# Set AWS credentials as environment variables (or configure ~/.aws/credentials) # export AWS_ACCESS_KEY_ID="your_access_key" # export AWS_SECRET_ACCESS_KEY="your_secret_key" # export AWS_DEFAULT_REGION="us-east-1" # Example: List S3 bucket content awscurl --service s3 'https://your-bucket-name.s3.amazonaws.com/'

awscurl --version

Debug

Known issues

gotchaCredential precedence can be confusing: Command-line arguments override environment variables, which in turn override values from `~/.aws/credentials` or `~/.aws/config` profiles.

fix

Always explicitly define credentials using the method with the highest precedence you intend to use. For debugging, use `--verbose` to see which credentials are being loaded.

affects: All versions

gotchaComplex query strings, particularly for Prometheus APIs with PromQL filters (e.g., `query={key="value"}`), may require manual URL encoding of the query string before passing it to `awscurl` to avoid `InvalidQueryStringException` errors.

fix

Manually URL-encode problematic parts of your query string, or the entire query string, before passing it via the `-d` flag or in the URI.

affects: All versions

breakingEarly versions (around v0.19) had issues with Python 3's byte/string handling, leading to unparsable JSON output (prefixed with `b'`).

fix

Upgrade `awscurl` to a newer version (0.20+) where Python 3 compatibility for output encoding has been addressed.

affects: <= 0.19

gotchaUsing `brew install awscurl` on macOS can sometimes lead to conflicts with existing Python installations or break the AWS CLI due to dependency version mismatches.

fix

Prefer `pip install awscurl` within a virtual environment. If using Homebrew, be aware of the Python versions it installs and how they interact with your system PATH. Consider running `awscurl` via Docker to isolate dependencies if conflicts arise.

affects: All versions (when installed via Homebrew)

gotchaBefore v0.34, if using AWS SSO or complex AWS CLI profiles, `botocore` might not have been automatically installed or loaded, leading to `botocore package could not be loaded` errors.

fix

Upgrade to `awscurl` v0.34 or later, which includes `botocore` as a default dependency. Alternatively, for older versions, ensure `pip install 'awscurl[awslibs]'` to include necessary AWS-related dependencies.

affects: < 0.34

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'awscurl'

This error occurs when the 'awscurl' package is not installed in the Python environment.

fix

Install the 'awscurl' package using pip: 'pip install awscurl'.

ImportError: cannot import name 'awscurl'

This error occurs when attempting to import 'awscurl' incorrectly or when the package is not installed.

fix

Ensure 'awscurl' is installed and import it correctly: 'import awscurl'.

awscurl: command not found

This error occurs when the 'awscurl' command-line tool is not installed or not in the system's PATH.

fix

Install 'awscurl' using pip: 'pip install awscurl', or ensure it's in your PATH.

awscurl: error: unrecognized arguments

This error occurs when invalid or unrecognized arguments are passed to the 'awscurl' command.

fix

Review the 'awscurl' usage and ensure all arguments are correct. Use 'awscurl --help' for guidance.

awscurl: error: the following arguments are required: uri

This error occurs when the 'awscurl' command is run without specifying a URI.

fix

Provide a valid URI when using 'awscurl', e.g., 'awscurl --service s3 https://my-bucket.s3.amazonaws.com'.

Upgrade

Version history

0.39latest on PyPI · released Mar 16, 2026

Audit

Dependencies

botocorerequiredDefault dependency for AWS service interaction and credential management.

configargparserequiredUsed for parsing command-line arguments, environment variables, and config files.

requestsrequiredAn elegant and simple HTTP library for Python, used for making HTTP requests.

urllib3requiredAn HTTP library with thread-safe connection pooling, used by 'requests'.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttp://github.com/okigan/awscurl ↗

packagehttps://pypi.org/project/awscurl/ ↗