# Using the Elastic Beanstalk Python platform
This topic describes how to configure, build, and run your Python applications on Elastic Beanstalk.
AWS Elastic Beanstalk supports a number of platform branches for different versions of the Python programming language. See [Python](https://docs.aws.amazon.com/elasticbeanstalk/latest/platforms/platforms-supported.html#platforms-supported.python) in the *AWS Elastic Beanstalk Platforms* document for a full list.
The Python web applications can run behind a proxy server with WSGI. Elastic Beanstalk provides [Gunicorn](https://gunicorn.org/) as the default WSGI server.
You can add a `Procfile` to your source bundle to specify and configure the WSGI server for your application. For details, see [Configuring the WSGI server with a Procfile on Elastic Beanstalk](python-configuration-procfile.md).
You can use the `Pipfile` and `Pipfile.lock` files created by Pipenv to specify Python package dependencies and other requirements. For details about specifying dependencies, see [Specifying dependencies using a requirements file on Elastic Beanstalk](python-configuration-requirements.md).
Elastic Beanstalk provides [configuration options](command-options.md) that you can use to customize the software that runs on the EC2 instances in your Elastic Beanstalk environment. You can configure environment variables needed by your application, enable log rotation to Amazon S3, and map folders in your application source that contain static files to paths served by the proxy server.
Configuration options are available in the Elastic Beanstalk console for [modifying the configuration of a running environment](environment-configuration-methods-after.md). To avoid losing your environment's configuration when you terminate it, you can use [saved configurations](environment-configuration-savedconfig.md) to save your settings and later apply them to another environment.
To save settings in your source code, you can include [configuration files](ebextensions.md). Settings in configuration files are applied every time you create an environment or deploy your application. You can also use configuration files to install packages, run scripts, and perform other instance customization operations during deployments.
Settings applied in the Elastic Beanstalk console override the same settings in configuration files, if they exist. This lets you have default settings in configuration files, and override them with environment-specific settings in the console. For more information about precedence, and other methods of changing settings, see [Configuration options](command-options.md).
For Python packages available from `pip`, you can include a requirements file in the root of your application source code. Elastic Beanstalk installs any dependency packages specified in a requirements file during deployment. For details, see [Specifying dependencies using a requirements file on Elastic Beanstalk](python-configuration-requirements.md).
For details about the various ways you can extend an Elastic Beanstalk Linux-based platform, see [Extending Elastic Beanstalk Linux platforms](platforms-linux-extend.md).
## Configuring your Python environment
The Python platform settings let you fine-tune the behavior of your Amazon EC2 instances. You can edit the Elastic Beanstalk environment's Amazon EC2 instance configuration using the Elastic Beanstalk console.
Use the Elastic Beanstalk console to configure Python process settings, enable AWS X-Ray, enable log rotation to Amazon S3, and configure variables that your application can read from the environment.
**To configure your Python environment in the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk), and in the **Regions** list, select your AWS Region.
1. In the navigation pane, choose **Environments**, and then choose the name of your environment from the list.
1. In the navigation pane, choose **Configuration**.
1. In the **Updates, monitoring, and logging** configuration category, choose **Edit**.
### Python settings
+ **Proxy server** – The proxy server to use on your environment instances. By default, nginx is used.
+ **WSGI Path** – The name of or path to your main application file. For example, `application.py`, or `django/wsgi.py`.
+ **NumProcesses** – The number of processes to run on each application instance.
+ **NumThreads** – The number of threads to run in each process.
### AWS X-Ray settings
+ **X-Ray daemon** – Run the AWS X-Ray daemon to process trace data from the [AWS X-Ray SDK for Python](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python.html).
### Log options
The Log Options section has two settings:
+ **Instance profile**– Specifies the instance profile that has permission to access the Amazon S3 bucket associated with your application.
+ **Enable log file rotation to Amazon S3** – Specifies whether log files for your application's Amazon EC2 instances are copied to the Amazon S3 bucket associated with your application.
### Static files
To improve performance, you can use the **Static files** section to configure the proxy server to serve static files (for example, HTML or images) from a set of directories inside your web application. For each directory, you set the virtual path to directory mapping. When the proxy server receives a request for a file under the specified path, it serves the file directly instead of routing the request to your application.
For details about configuring static files using configuration files or the Elastic Beanstalk console, see [Serving static files](environment-cfg-staticfiles.md).
By default, the proxy server in a Python environment serves any files in a folder named `static` at the `/static` path. For example, if your application source contains a file named `logo.png` in a folder named `static`, the proxy server serves it to users at `subdomain.elasticbeanstalk.com/static/logo.png`. You can configure additional mappings as explained in this section.
### Environment properties
You can use environment properties to provide information to your application and configure environment variables. For example, you can create an environment property named `CONNECTION_STRING` that specifies a connection string that your application can use to connect to a database.
Inside the Python environment running in Elastic Beanstalk, these values are accessible using Python's `os.environ` dictionary. For more information, see [http://docs.python.org/library/os.html](http://docs.python.org/library/os.html).
You can use code that looks similar to the following to access the keys and parameters:
```
import os
endpoint = os.environ['API_ENDPOINT']
```
Environment properties can also provide information to a framework. For example, you can create a property named `DJANGO_SETTINGS_MODULE` to configure Django to use a specific settings module. Depending on the environment, the value could be `development.settings`, `production.settings`, etc.
See [Environment variables and other software settings](environments-cfg-softwaresettings.md) for more information.
## Python configuration namespaces
You can use a [configuration file](ebextensions.md) to set configuration options and perform other instance configuration tasks during deployments. Configuration options can be [platform specific](command-options-specific.md) or apply to [all platforms](command-options-general.md) in the Elastic Beanstalk service as a whole. Configuration options are organized into *namespaces*.
The Python platform defines options in the `aws:elasticbeanstalk:environment:proxy`, `aws:elasticbeanstalk:environment:proxy:staticfiles`, and `aws:elasticbeanstalk:container:python` namespaces.
The following example configuration file specifies configuration option settings to create an environment property named `DJANGO_SETTINGS_MODULE`, choose the Apache proxy server, specify two static files options that map a directory named `statichtml` to the path `/html` and a directory named `staticimages` to the path `/images`, and specify additional settings in the `[aws:elasticbeanstalk:container:python](command-options-specific.md#command-options-python)` namespace. This namespace contains options that let you specify the location of the WSGI script in your source code, and the number of threads and processes to run in WSGI.
```
option_settings:
aws:elasticbeanstalk:application:environment:
DJANGO_SETTINGS_MODULE: production.settings
aws:elasticbeanstalk:environment:proxy:
ProxyServer: apache
aws:elasticbeanstalk:environment:proxy:staticfiles:
/html: statichtml
/images: staticimages
aws:elasticbeanstalk:container:python:
WSGIPath: ebdjango.wsgi:application
NumProcesses: 3
NumThreads: 20
```
**Notes**
If you're using an Amazon Linux AMI Python platform version (preceding Amazon Linux 2), replace the value for `WSGIPath` with `ebdjango/wsgi.py`. The value in the example works with the Gunicorn WSGI server, which isn't supported on Amazon Linux AMI platform versions.
In addition, these older platform versions use a different namespace for configuring static files—`aws:elasticbeanstalk:container:python:staticfiles`. It has the same option names and semantics as the standard static file namespace.
Configuration files also support several keys to further [modify the software on your environment's instances](customize-containers-ec2.md). This example uses the [packages](customize-containers-ec2.md#linux-packages) key to install Memcached with `yum` and [container commands](customize-containers-ec2.md#linux-container-commands) to run commands that configure the server during deployment:
```
packages:
yum:
libmemcached-devel: '0.31'
container_commands:
collectstatic:
command: "django-admin.py collectstatic --noinput"
01syncdb:
command: "django-admin.py syncdb --noinput"
leader_only: true
02migrate:
command: "django-admin.py migrate"
leader_only: true
03wsgipass:
command: 'echo "WSGIPassAuthorization On" >> ../wsgi.conf'
99customize:
command: "scripts/customize.sh"
```
Elastic Beanstalk provides many configuration options for customizing your environment. In addition to configuration files, you can also set configuration options using the console, saved configurations, the EB CLI, or the AWS CLI. See [Configuration options](command-options.md) for more information.
## The `python3` executable
The version of the `python3` executable available on EC2 instances in Elastic Beanstalk Python environments will not always correspond to the same Python version used by the platform. For example, on the Python 3.12 AL2023 platform, `/usr/bin/python3` points to Python 3.9. This is because Python 3.9 is the *system Python* on AL2023. For more information, see [Python in AL2023](https://docs.aws.amazon.com/linux/al2023/ug/python.html) in the *Amazon Linux 2023 User Guide*. You can access an executable corresponding to the Python version used by the platform at a versioned location (e.g. `/usr/bin/python3.12`) or in the application virtual environment `bin` directory (e.g. `/var/app/venv/staging-LQM1lest/bin/python3`). The platform uses the correct Python executable that corresponds to the platform branch.
# Configuring the WSGI server with a Procfile on Elastic Beanstalk
You can add a [`Procfile`](platforms-linux-extend.build-proc.md#platforms-linux-extend.proc) to your source bundle to specify and configure the WSGI server for your application. You can specify custom start and run commands in the `Procfile`.
When you use a `Procfile`, it overrides `aws:elasticbeanstalk:container:python` namespace options that you set using configuration files.
The following example uses a `Procfile` to specify uWSGI as the server and configure it.
**Example Procfile**
```
web: uwsgi --http :8000 --wsgi-file application.py --master --processes 4 --threads 2
```
The following example uses a `Procfile` to configure Gunicorn, the default WSGI server.
**Example Procfile**
```
web: gunicorn --bind :8000 --workers 3 --threads 2 project.wsgi:application
```
**Notes**
If you configure any WSGI server other than Gunicorn, be sure to also specify it as a dependency of your application, so that it is installed on your environment instances. For details about dependency specification, see [Specifying dependencies using a requirements file on Elastic Beanstalk](python-configuration-requirements.md).
The default port for the WSGI server is 8000. If you specify a different port number in your `Procfile` command, set the `PORT` [environment property](environments-cfg-softwaresettings.md) to this port number too.
# Specifying dependencies using a requirements file on Elastic Beanstalk
This topic describes how to configure you application to install other Python packages that it requires. A typical Python application has dependencies on other third-party Python packages. With the Elastic Beanstalk Python platform, you have multiple ways to specify Python packages that your application depends on.
## Use `pip` and `requirements.txt`
The standard tool for installing Python packages is `pip`. It has a feature that allows you to specify all the packages you need (as well as their versions) in a single requirements file. For more information about the requirements file, see [Requirements File Format](https://pip.pypa.io/en/latest/reference/requirements-file-format/#requirements-file-format) on the pip documentation website.
Create a file named `requirements.txt` and place it in the top-level directory of your source bundle. The following is an example `requirements.txt` file for Django.
```
Django==2.2
mysqlclient==2.0.3
```
In your development environment, you can use the `pip freeze` command to generate your requirements file.
```
~/my-app$ pip freeze > requirements.txt
```
To ensure that your requirements file only contains packages that are actually used by your application, use a [virtual environment](python-development-environment.md#python-common-setup-venv) that only has those packages installed. Outside of a virtual environment, the output of `pip freeze` will include all `pip` packages installed on your development machine, including those that came with your operating system.
**Note**
On Amazon Linux AMI Python platform versions, Elastic Beanstalk doesn't natively support Pipenv or Pipfiles. If you use Pipenv to manage your application's dependencies, run the following command to generate a `requirements.txt` file.
```
~/my-app$ pipenv lock -r > requirements.txt
```
To learn more, see [Generating a requirements.txt](https://pipenv.readthedocs.io/en/latest/advanced/#generating-a-requirements-txt) in the Pipenv documentation.
## Use Pipenv and `Pipfile`
Pipenv is a modern Python packaging tool. It combines package installation with the creation and management of a dependency file and a virtualenv for your application. For more information, see [Pipenv: Python Dev Workflow for Humans](https://pipenv.readthedocs.io/en/latest/).
Pipenv maintains two files:
+ `Pipfile` — This file contains various types of dependencies and requirements.
+ `Pipfile.lock` — This file contains a version snapshot that enables deterministic builds.
You can create these files on your development environment and include them in the top-level directory of the source bundle that you deploy to Elastic Beanstalk. For more information about these two files, see [Example Pipfile and Pipfile.lock](https://pipenv.pypa.io/en/latest/basics/#).
The following example uses Pipenv to install Django and the Django REST framework. These commands create the files `Pipfile` and `Pipfile.lock`.
```
~/my-app$ pipenv install django
~/my-app$ pipenv install djangorestframework
```
## Precedence
If you include more than one of the requirements files described in this topic, Elastic Beanstalk uses just one of them. The following list shows the precedence, in descending order.
1. `requirements.txt`
1. `Pipfile.lock`
1. `Pipfile`
**Note**
Starting with the March 7, 2023 Amazon Linux 2 platform release, if you provide more than one of these files, Elastic Beanstalk will issue a console message stating which one of the dependency files was used during a deployment.
The following steps describe the logic that Elastic Beanstalk follows to install the dependencies when it's deploying an instance.
+ If there is a `requirements.txt` file, we use the command `pip install -r requirements.txt`.
+ Starting with the March 7, 2023 Amazon Linux 2 platform release, if there is no `requirements.txt` file, but there is a `Pipfile.lock`, we use the command `pipenv sync`. Prior to that release, we used `pipenv install --ignore-pipfile`.
+ If there is neither a `requirements.txt` file nor a `Pipfile.lock`, but there is a `Pipfile`, we use the command `pipenv install --skip-lock`.
+ If none of the three requirements files are found, we don't install any application dependencies.