Install & Compatibility
Where this runs
tested against v1.33.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.059s · 63MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.3s · import 0.053s · 64MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Chalice
✓ from chalice import Chalice
Response
✓ from chalice import Response
Used for customizing HTTP responses (status codes, headers, non-JSON bodies).
Rate, Cron
✓ from chalice import Rate, Cron
Used with @app.schedule decorator for defining scheduled events.
This quickstart demonstrates how to define a basic REST API with Chalice. After installing Chalice and configuring AWS credentials, create a new project using `chalice new-project <project-name>`, then update `app.py` with the provided code. Deploy the application to AWS Lambda and API Gateway with `chalice deploy`.
import os
from chalice import Chalice
# Configure AWS credentials if not already set up via AWS CLI
# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_KEY')
# os.environ['AWS_DEFAULT_REGION'] = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
app = Chalice(app_name='my-first-chalice-app')
@app.route('/')
def index():
return {'hello': 'world'}
@app.route('/greet/{name}')
def greet_name(name):
return {'message': f'Hello, {name}!'}
# To deploy:
# 1. Ensure AWS CLI is configured with credentials.
# 2. Run `chalice new-project my-first-chalice-app`
# 3. Replace the generated `app.py` content with the code above.
# 4. Run `chalice deploy` in your project directory.
# To test locally: `chalice local`
# To delete: `chalice delete`
chalice --version
Debug
Known issues
gotchaChalice automatically generates IAM policies for your Lambda functions. While convenient, these auto-generated policies can sometimes be overly permissive. For production environments, it's recommended to review the generated policies (in `.chalice/policy.json`) and manually refine them or disable auto-generation using `manage_iam_role=False` in `config.json` or the `--no-autogen-policy` flag during deployment for fine-grained control.fixManually review `.chalice/policy.json` and refine permissions, or use `manage_iam_role=False` in `.chalice/config.json` and provide your own IAM role ARN.
affects: All versions
gotchaWhen using `chalice local` for local development and testing, the application runs in your local environment and uses your configured AWS CLI credentials, not the IAM role that would be assumed by the Lambda function in AWS. Ensure your local AWS profile has the necessary permissions to access any AWS services (e.g., DynamoDB, S3) your application interacts with during local testing.fixEnsure your local AWS CLI profile (e.g., `~/.aws/credentials`, `~/.aws/config`) has sufficient permissions for all AWS services your Chalice app uses.
affects: All versions
breakingThe `@app.on_s3_event` decorator, used for triggering Lambda functions from S3 events, is incompatible with the `chalice package` command. If your application uses S3 event sources, you cannot use `chalice package` to generate a CloudFormation/SAM template; you must deploy directly using `chalice deploy`.fixIf using `@app.on_s3_event`, use `chalice deploy` for direct deployment rather than `chalice package`.
affects: All versions
gotchaAWS Lambda has specific Python runtime versions it supports. While Chalice aims to support these, always verify that your local Python environment matches a supported AWS Lambda runtime (e.g., Python 3.9 through 3.13 are currently supported) to avoid deployment issues or unexpected behavior.fixCheck AWS Lambda's current Python runtime support and ensure your development environment and `runtime` configuration in `.chalice/config.json` are compatible.
affects: Older versions might have narrower support, but current versions align with AWS Lambda's latest runtimes.
Errors
Common errors & fixes
Unable to import module 'app': No module named 'app'
Chalice, when deploying to AWS Lambda, cannot find the main `app.py` file or a module it tries to import. This often happens if the file is not named `app.py`, is in the wrong directory, or if external dependencies are not correctly packaged.
fixEnsure your main application file is named `app.py` in the root of your Chalice project. For missing dependencies, add them to `requirements.txt` and ensure they are compatible with the Lambda runtime, or manually vendor them into a `vendor/` directory if they have C extensions or aren't pip-installable on the deployment platform.
An error occurred (RequestEntityTooLargeException) when calling the PublishLayerVersion operation: Request must be smaller than [...] bytes for the PublishLayerVersion operation This is likely because the deployment package is [...] MB. Lambda only allows deployment packages that are 50.0 MB or less in size.
The total size of your Chalice deployment package (including your code and all dependencies) exceeds the AWS Lambda deployment package size limit (typically 50MB unzipped).
fixReduce the size of your application by removing unnecessary code or dependencies. Consider using Lambda Layers to manage larger dependencies, or switch to container images for deployment if your application is significantly large (up to 10GB).
An error occurred (InvalidClientTokenId) when calling the GetRole operation: The security token included in the request is invalid.
Chalice deployment fails because the AWS credentials configured (e.g., in `~/.aws/credentials` or environment variables) are invalid, expired, or lack the necessary permissions to perform AWS operations like `GetRole`.
fixVerify your AWS credentials by running `aws configure` and ensuring the `aws_access_key_id` and `aws_secret_access_key` are correct and associated with an IAM user or role that has permissions to deploy Chalice applications (e.g., `AWSChaliceFullAccess` or a custom policy with equivalent permissions).
ChaliceViewError: An internal server error occurred.
This is a generic error from Chalice indicating that an unhandled exception occurred within your Lambda function's Python code during execution.
fixCheck your AWS CloudWatch logs for the specific Lambda function. The detailed traceback in CloudWatch will reveal the exact Python exception (e.g., `KeyError`, `AttributeError`, `TypeError`) that caused the internal server error, allowing you to debug and fix your application code.
Could not install dependencies: <package_name> You will have to build these yourself and vendor them in the chalice vendor folder.
Chalice's packaging process (which uses `pip`) was unable to find or build a compatible wheel for a specific dependency listed in `requirements.txt`. This commonly occurs for packages that include C extensions and do not provide pre-compiled wheels for the Amazon Linux environment that Lambda runs on.
fixManually build the problematic package on an Amazon Linux environment (e.g., an EC2 instance or Docker container mimicking Lambda's environment) and then place the compiled package files into your Chalice project's `vendor/` directory. Chalice will automatically include anything in this directory in the deployment package.
Upgrade
Version history
1.33.0latest on PyPI · released May 7, 2026
Audit
Dependencies
boto3requiredChalice internally uses the AWS SDK for Python to interact with AWS services, including deployment and runtime operations.
awsclioptionalRequired for configuring AWS credentials, which Chalice relies on for deployment and local testing.