Guides
Python

Deploy Python Projects

Zeabur supports various types of Python projects, including:

If your source code includes app.py, main.py, or similar entry points, Zeabur will also start automatically.

NPM Support

If your project root contains a package.json, Zeabur will automatically install Node.js and NPM for you; if your package.json contains a build script, Zeabur will automatically run npm install && npm run build to build the artifacts.

If you need to change the build commands (e.g., to run npm run build:dist), please refer to the section on Customizing Build and Start Commands.

Customizing Build and Start Commands

Zeabur allows you to customize Python build and start commands using environment variables or configuration files.

"Build commands" are suitable for scenarios where you need to download or compile custom artifacts (such as CSS, JavaScript, etc.) or write constant configurations. For example, if you want to write settings to the /etc folder, you can set an environment variable like this:

ZBPACK_BUILD_COMMAND=echo 'your-configuration' > /etc/somewhere

Or add the following settings in zbpack.json:

{
    "build_command": "echo 'your-configuration' > /etc/somewhere"
}

You can also execute npm commands here. Note that Zeabur will only install Node.js and NPM if there is a package.json in the project root directory. If your project does not contain a package.json, npm commands will not be available:

{
    "build_command": "npm install && npm run build:dist"
}

"Start commands" are suitable for scenarios when you need to run command before starting a Python application, such as adding python3 migrate.py to the original command to migrate database. For example, you can set an environment variable like this:

ZBPACK_START_COMMAND="python3 migrate.py && _startup"

Or add the following settings in zbpack.json:

{
    "start_command": "python3 migrate.py && _startup"
}

Here, _startup is Zeabur's original start command (which can be found in the zbpack source code (opens in a new tab)). If you have a custom start_command, _startup must be included in your start command; otherwise, the Python application will not start.

Both build_command and start_command will be executed using a POSIX-compliant shell, so you can use && to chain multiple commands, or use ; to separate multiple commands.

Serverless

Zeabur supports deploying Python projects as serverless projects. However, this currently requires opt-in. Please refer to the Enable Serverless page to enable your serverless support.

Setting the Python Version

Zeabur uses Python 3.10 as the default runtime environment. However, Zeabur will select the runtime environment based on the Python version set in your project. You can also customize the runtime environment as needed.

Specifying the Python Version in Your Project

Specifying the Python version in your project is a more general approach that works in all environments.

For Pipenv, specify the Python version in the Pipfile (opens in a new tab):

[requires]
python_version = "3.8"   # Specify the Python version here

For Poetry, specify the Python version in the pyproject.toml (opens in a new tab)

[tool.poetry.dependencies]
python = "^3.8"  # Specify the Python version here

For PDM, specify the requires-python in the pyproject.toml (opens in a new tab):

[project]
requires-python = ">= 3.8"  # Specify the Python version here

For Rye, use the rye pin command to set the Python version (opens in a new tab):

rye pin 3.8  # Specify the Python version here

Specifying the Python Version in Zeabur

If you are using the traditional requirements.txt or need to override the Python version specified in your project for Zeabur, you can specify the Python version in zbpack.json.

{
    "python": {
        "version": "3.8"
    }
}

Alternatively, use the ZBPACK_PYTHON_VERSION environment variable to specify the Python version:

ZBPACK_PYTHON_VERSION=3.8

Specifying the Streamlit Entry File

If you have declared the streamlit dependency in your project, and the filename is one of app.py, main.py, and streamlit_app.py, Zeabur will default to launching your application in Streamlit mode.

However, if your filename is not one of these three, you can specify the filename in the zbpack.json. For example, if your Streamlit application's filename is myapp.py:

{
    "streamlit": {
        "entry": "myapp.py"
    }
}

This way, Zeabur will launch your myapp.py in Streamlit mode. You can also specify the filename using the environment variable ZBPACK_STREAMLIT_ENTRY:

ZBPACK_STREAMLIT_ENTRY=myapp.py