# awslocal: the deprecated LocalStack wrapper you should be migrating away from > awscli-local provides awslocal, a thin wrapper that points the aws command line interface at a local LocalStack endpoint, and the project now opens with a warning that it is deprecated in favour of lstk aws. That makes its own end of life a migration problem rather than a curiosity. **localstack/awscli-local** — 💲 "awslocal" - Thin wrapper around the "aws" command line interface for use with LocalStack - Repository: https://github.com/localstack/awscli-local - Stars: 1,303 · Forks: 94 - Language: Python - License: Apache-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/localstack-awscli-local ## The deprecation notice is the first thing in the README The repository opens with a warning block that sets the whole context. awslocal is deprecated, and the instruction is to use lstk aws instead. awslocal no longer receives updates. Two links are given. The first is the getting started page for lstk, the new LocalStack CLI. The second is the migration page, and it is specifically about infrastructure as code, with the anchor pointing at that section of the migration guide. Then there is a detail that catches people out during a migration. lstk aws does not install the AWS CLI for you. If you used awscli-local[ver1] to install it, the instruction is to install the AWS CLI separately before you switch. So the deprecation is not a simple rename. There is a new command, and the new command has a different installation contract, and the difference matters most in CI where the AWS CLI was previously a side effect of installing the wrapper. What the project is underneath all of that is small on purpose. It provides the awslocal command, which is a thin wrapper around the aws command line interface for use with LocalStack. The setup.py is honest about the shape of it, listing the scripts as bin/awslocal and bin/awslocal.bat with an empty packages list, because there is no library to import, only an executable to install. The single install_requires dependency is localstack-client. For anyone who arrives at this repository today, the correct reading is that you are looking at the end of a project, not the start of one, and the question is how long your existing scripts keep working. ## What the wrapper actually does with the endpoint The core trick is small enough to describe in one sentence, and the README shows both forms. Instead of this: ```console aws --endpoint-url=http://localhost:4566 kinesis list-streams ``` you can use this: ```console awslocal kinesis list-streams ``` The awslocal command has the same usage as the aws command, and for detailed usage the documentation points you at the manual pages of aws help. That equivalence is the point. Every flag, every service, every argument works the same, and the wrapper only changes where the requests go. The endpoint comes from environment variables, and there are three of them with a precedence order that is worth knowing. AWS_ENDPOINT_URL is the endpoint URL to connect to, and it takes precedence over USE_SSL and LOCALSTACK_HOST. The documentation describes it as useful when you have LocalStack bound to a different host, for example within docker-compose. LOCALSTACK_HOST is marked deprecated. It is a hostname:port variable defining where to find LocalStack, with a default of localhost:4566. USE_SSL is also marked deprecated. It says whether to use SSL when connecting to LocalStack, with a default of False. DISABLE_DEPRECATION_NOTICE is the fourth variable, and it is about the wrapper rather than the endpoint. Setting it to 1 hides the deprecation notice, with the default unset. So there are two separate deprecation axes here, and they are easy to conflate. LOCALSTACK_HOST and USE_SSL are deprecated as configuration, replaced by AWS_ENDPOINT_URL. And awslocal itself is deprecated as a command, replaced by lstk aws. A team running on LOCALSTACK_HOST today has two migrations to think about, and the first one is the smaller. ## The cloudformation package limitation, and why it comes from the AWS side The limitations section names one specific broken thing, and the diagnosis is more interesting than the workaround. There is a known limitation for using the cloudformation package command with the AWS CLI v2. Currently it is not possible to specify the S3 endpoint URL, and the issue is not yet resolved on the AWS side, with a link to the upstream aws-cli pull request. The explanation given is a chain of causes. The AWS CLI v2 is not available as a package on pypi.org and is instead shipped as a binary package that cannot be easily patched from awslocal. The wrapper has to work around the fact that cloudformation package uploads to S3, and the S3 endpoint is not pointed at LocalStack, so the upload goes somewhere it should not. There are two documented workarounds, and the project is explicit about which it prefers. Downgrade to the v1 AWS CLI, and this is the recommended approach. The second is an unofficial way to install AWS CLI v2 from sources, which the project says is technically possible but not recommended, with a note to install the libraries in a Python virtualenv to avoid version clashes with other libraries on the system. ```sh virtualenv .venv . .venv/bin/activate pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip ``` That last detail explains why the package layout is what it is. The ver1 extra exists because pip cannot install CLI v2, so the only supported way to get a working AWS CLI alongside the wrapper is v1 from PyPI. The changelog shows the other side of the same coin. Version 0.15 fixed the lookup of the v1 and v2 AWS CLI version and applied --s3-endpoint-url only for v1, and version 0.9 added --s3-endpoint-url by default to fix the cloudformation package command. This is a wrapper that spends its life working around the fact that the AWS CLI ships two incompatible ways. ## The in-memory aws command, and why it changed the wrapper's behaviour One changelog entry explains a lot about how the wrapper works today. Version 0.6 started the aws CLI command in memory instead of calling an external process. That is a meaningful architectural change for something described as a thin wrapper. Calling an external process means spawning the aws binary, letting it resolve its own configuration, and parsing its output. Running it in memory means the wrapper imports the CLI's own machinery and drives it directly, which is faster and, more importantly, lets the wrapper intercept the endpoint resolution and the S3 endpoint flag rather than hoping the child process picks them up. A few other entries point at the same area. Version 0.22.0 added a fallback for endpoint detection, with the stated goal of preventing most cases of the error message about being unable to find the LocalStack endpoint for a service. Version 0.19 patched botocore to stop it adding data- host prefixes to endpoint URLs, and version 0.21.1 introduced semantic versioning along with a list of services that have no endpoints,. Version 0.21 used placeholder credentials and region only if Boto cannot find them. That last one is a sensible default for a local emulator. Against LocalStack, credentials are not really credentials, so a wrapper that invents them when none are configured saves every user from setting fake keys in every environment. Other entries are more prosaic and still instructive about the shape of the tool. Version 0.22.2 changed error output so that full stack traces appear only in --debug mode and non-debug runs show concise error messages, consistent with awscli behaviour. Version 0.18 passes the SYSTEMROOT environment variable to fix a hash randomisation error on Windows. Version 0.14 quotes file names on Windows to allow folder names with spaces. Version 0.5 added support for piping binary files to stdout and a.bat file for Windows. ## Shell completion, which is the feature people miss until they want it The completion section is worth a paragraph, because it is the feature that makes awslocal feel like a first class command rather than a script. The awscli package provides a command completion feature which is compatible with most modern shells, and which can also be used with awslocal. The completion automatically suggests commands and parameters when using the completion key, typically the Tab key. ```sh $ awslocal dynamodb d delete-backup describe-global-table delete-item describe-global-table-settings delete-table describe-limits describe-backup describe-table describe-continuous-backups describe-table-replica-auto-scaling describe-contributor-insights describe-time-to-live describe-endpoints ``` The configuration requirement is the part people miss. You follow the official guide for setting up command completion for the aws CLI, and while enabling it for your shell you must make sure to register the completion for awslocal as well. For bash, the README shows adding two lines to your ~/.bashrc. ```sh complete -C '/usr/local/bin/aws_completer' aws complete -C '/usr/local/bin/aws_completer' awslocal ``` For other shells, you follow the instructions for the shell you use, and for some you might need to register a different command or enable certain compatibility plugins, with zsh named as an example. That is the whole mechanism. There is no separate completion implementation in this repository, the wrapper reuses the one the aws CLI ships, and the only work is registering the second name. A thin wrapper that inherits a capability rather than reimplementing it is a good sign for the rest of the project. ## The package build, and the shape of the repository The repository is small and the build is a conventional Python packaging setup, which makes sense for a project with a single executable and no library. The top level holds .github/, .gitignore, LICENSE, Makefile, README.md, a bin/ directory with the scripts, an output/ directory, requirements.txt, setup.py and a tests/ directory. The Makefile has an install target that creates a virtualenv in .venv and installs the requirements into it, a publish target that builds the archive and uploads it with twine, a lint target that runs flake8 on bin/awslocal while ignoring E501 and W503, and a clean target that removes the virtualenv. The setup.py metadata is where the version lives, and it is 0.23.0, matching the top entry in the changelog. The extras_require section has one entry, ver1, which maps to awscli. That is the whole of the dependency negotiation with the AWS CLI, and it is the one that causes the v2 pain described earlier. The requirements.txt is a single line, localstack-client, which is the same as the install_requires. The classifiers are a slightly odd artefact. They list Python 2, 2.6, 2.7 and 3.3 through 3.9, which reflects the package's long history rather than its current testing matrix, and the changelog confirms the age with a v0.20 entry about small fixes for Python 2.x backward compatibility. There is also a Topic classification of Software Development and Testing, which is a fair description of what the tool is for even if it understates the audience. The licence is Apache License 2.0, declared in setup.py and with a LICENSE file at the root. ## Conclusion awslocal fits an existing team whose scripts, CI jobs and developer habits already call awslocal and who need to keep them working while they move, since the wrapper is a single pip install away and the endpoint configuration is a set of environment variables rather than code. It does not fit a new project, because the project itself says awslocal no longer receives updates and points you at lstk aws instead. Check three things before you decide. Check whether your scripts depend on the v1 AWS CLI, because the extra awscli-local[ver1] install exists to pull in CLI v1 and the cloudformation package command is known to be broken with v2 in a way that has not been resolved upstream. Check your endpoint configuration, because AWS_ENDPOINT_URL takes precedence over the two older variables and that precedence is the one that surprises people. And check where the deprecation notice is going to land in your CI output, since it prints on every run unless you set DISABLE_DEPRECATION_NOTICE to 1, and silencing it is a decision rather than a fix. The last push was on 2026-10-09, the package version is 0.23.0, and the license is Apache-2.0. ## FAQ ### Is awslocal deprecated? Yes. The README opens with a warning that awslocal is deprecated and that it no longer receives updates, and directs users to lstk aws, the new LocalStack CLI, with links for getting started and for migrating scripts and CI workflows. ### How do I install awslocal? With pip install awscli-local[ver1], which also installs the AWS CLI version 1 package. If you manage your own awscli version, install just the wrapper with pip install awscli-local. On macOS or with ZSH, quote the package name. ### Which environment variables does awslocal read? AWS_ENDPOINT_URL for the endpoint URL, which takes precedence over the two older variables. LOCALSTACK_HOST and USE_SSL are both marked deprecated, with defaults of localhost:4566 and False. DISABLE_DEPRECATION_NOTICE set to 1 hides the deprecation notice. ### What is broken with awslocal and the AWS CLI v2? The cloudformation package command cannot specify the S3 endpoint URL with AWS CLI v2, and the project links an unresolved upstream issue. The recommended workaround is to downgrade to the v1 AWS CLI. ### How do I get shell completion working with awslocal? Set up completion for the aws CLI following the official guide, then register the completion for awslocal as well, for example by adding a complete -C line for awslocal to your ~/.bashrc alongside the one for aws. Some shells need a different command or compatibility plugins. ### What license is awscli-local released under? Apache License 2.0, declared in setup.py with a LICENSE file at the root of the repository. The package version is 0.23.0, and the last push was on 2026-10-09. ## Sources - [Issues](https://github.com/localstack/awscli-local/issues) - [License: Apache-2.0](https://github.com/localstack/awscli-local/blob/master/LICENSE) - [localstack/awscli-local on GitHub](https://github.com/localstack/awscli-local) - [README](https://github.com/localstack/awscli-local/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/localstack-awscli-local