Registry / aws / awscli-local

awscli-local

library0.22.2pypypiunverified

awscli-local is a thin Python wrapper around the standard 'aws' command-line interface (CLI) that enables seamless interaction with LocalStack, a cloud service emulator. It allows developers to execute AWS CLI commands against their local LocalStack instance without needing to explicitly specify the `--endpoint-url` parameter. The current version is 0.22.2, and it is actively maintained by the LocalStack team, receiving regular updates.

aws devops

pip install awscli-local[ver1]

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWSCLI-LOCAL

awscli-local

awspythonv0.22.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This quickstart demonstrates creating and listing an S3 bucket using the `awslocal` command, assuming LocalStack is already running on your machine. This eliminates the need for `--endpoint-url` on most commands.

# First, ensure LocalStack is running (e.g., via `localstack start` or Docker). # Then, use awslocal as you would aws, but interacting with your local services. awslocal s3 mb s3://my-local-bucket awslocal s3 ls

awslocal --version

Debug

Known issues

breakingAutomatic installation of AWS CLI version 2 (AWS CLI v2) is not directly supported via `pip install awscli-local[ver2]` because AWS CLI v2 is not officially available as a PyPI package. While `awslocal` can technically work with a manually installed AWS CLI v2, it's generally recommended to stick with AWS CLI v1 (installed via `awscli-local[ver1]`) to avoid potential issues and limitations.

fix

Use `pip install awscli-local[ver1]` to install the wrapper with AWS CLI v1. If AWS CLI v2 is desired, install it separately (e.g., using the official AWS installer) and ensure `awslocal`'s PATH is correctly configured. Be aware of known limitations, particularly for CloudFormation.

affects: All versions

gotchaAfter installing `awscli-local` via pip, users might encounter 'awslocal: command not found'. This typically means the executable's location is not in the system's PATH environment variable, or the shell hasn't refreshed its PATH after installation.

fix

Ensure the directory where `awslocal` is installed (e.g., `~/.local/bin` for user installs, or a virtual environment's `bin` directory) is included in your PATH. Reload your shell by sourcing its configuration file (e.g., `source ~/.bashrc` or `source ~/.zshrc`) or by opening a new terminal window.

affects: All versions

deprecatedEnvironment variables `LOCALSTACK_HOST` and `USE_SSL` are deprecated for configuring the LocalStack endpoint. They have been replaced by `AWS_ENDPOINT_URL`.

fix

Use the `AWS_ENDPOINT_URL` environment variable (e.g., `export AWS_ENDPOINT_URL=http://localhost:4566`) instead of `LOCALSTACK_HOST` or `USE_SSL`.

affects: All versions

breakingThere is a known limitation when using AWS CLI v2 for `cloudformation package` commands: it is not possible to specify the S3 endpoint URL. This issue affects deploying CloudFormation templates with S3 assets via `awslocal` when backed by AWS CLI v2.

fix

The recommended workaround is to downgrade to AWS CLI v1 for `cloudformation` commands by installing `awscli-local[ver1]`. Alternatively, for advanced use cases, consider directly interacting with LocalStack's S3 service for asset storage.

affects: All versions (when using AWS CLI v2)

Errors

Common errors & fixes

awslocal: command not found

The 'awslocal' command is not in the system's PATH after installing 'awscli-local'.

fix

Ensure the installation directory is in your PATH, or use the full path to 'awslocal'.

zsh: no matches found: awscli-local[ver1]

Zsh interprets square brackets as glob patterns, causing an error when installing extras with pip.

fix

Escape the brackets or quote the package name: pip install 'awscli-local[ver1]'

ModuleNotFoundError: No module named 'awscli'

The 'awscli' module is not installed or is corrupted.

fix

Reinstall the AWS CLI: python3 -m pip install --upgrade --force-reinstall awscli

Could not connect to the endpoint URL

The `awslocal` command is unable to reach the LocalStack instance, which might be due to LocalStack not running, an incorrect endpoint configuration, or network connectivity issues (e.g., firewall).

fix

Ensure your LocalStack instance is running. Verify that `LOCALSTACK_HOST` or `AWS_ENDPOINT_URL` environment variables are correctly set (e.g., `export LOCALSTACK_HOST=localhost:4566`) or that LocalStack is accessible on the default `localhost:4566`. Check for any local firewall rules blocking the connection.

Permission denied

The user attempting to run `awslocal` or during its installation does not have the necessary read, write, or execute permissions for the CLI executable or its configuration files/directories.

fix

For installation, try running with `sudo` if on Linux/macOS (`sudo pip install awscli-local`). If the issue occurs during execution, check and adjust file/directory permissions for the `awslocal` executable and the `.aws` configuration directory (e.g., `chmod -R 755 /usr/local/aws-cli` for common Linux installations).

Upgrade

Version history

0.22.2latest on PyPI · released Aug 7, 2025

Audit

Dependencies

awsclirequiredCore functionality; awscli-local is a wrapper around the AWS CLI. The `[ver1]` extra specifically installs AWS CLI v1.

localstack-clientrequiredUsed internally by the `awslocal` script for configuration and endpoint detection.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/localstack/awscli-local ↗

packagehttps://pypi.org/project/awscli-local/ ↗

homepagehttps://www.localstack.cloud ↗