Deploy Python Projects

Zeabur supports various types of Python projects, including:

Flask
Django
FastAPI

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.

Customize Entrypoint

Zeabur will recognize main.py, app.py, manage.py, server.py, app/__init__.py as entry points by default. If your entry point is not listed above, you can set an environment variable

ZBPACK_PYTHON_ENTRY=your-entrypoint.py

Or add the following setting to zbpack.json:

{
    "python": {
        "entry": "your-entrypoint.py"
    }
}

This way, Zeabur will use your-entrypoint.py as the Python executable file.

If you want to deploy WSGI/ASGI applications (such as Django, Flask, FastAPI) and the entry point is in __init__.py, you need to provide the full path (including __init__.py):

# server/__init__.py
 
app = Flask(__name__)

ZBPACK_PYTHON_ENTRY=server/__init__.py

If your entry point is in __main__.py, you also need to provide the full path:

# server/__main__.py
 
print("Hello!")

ZBPACK_PYTHON_ENTRY=server/__main__.py

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). 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.

Web Scraping

Playwright Support

If your dependency list (requirements.txt, Pipfile, pyproject.toml, etc.) declares playwright, Zeabur will automatically prepare the necessary environment to run Playwright.

Note that Playwright should be run in Headless mode, which is usually the default.

Selenium Support

If your dependency list (requirements.txt, Pipfile, pyproject.toml, etc.) declares seleniumbase or selenium, Zeabur will automatically prepare the necessary environment to run Selenium.

Note that Selenium should be run in Headless mode.

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:

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

For Poetry, specify the Python version in the pyproject.toml：

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

For PDM, specify the requires-python in the pyproject.toml:

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

For Rye, use the rye pin command to set the Python version:

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

Specifying the Package Manager

Zeabur supports multiple Python package managers:

Zeabur determines the most suitable package manager based on the project structure. If you haven’t committed your lockfile and the package manager used in the project is unclear, Zeabur will not install any packages. In this case, you can specify the package manager in zbpack.json:

{
    "python": {
        "package_manager": "pipenv"
    }
}

Alternatively, you can use the ZBPACK_PYTHON_PACKAGE_MANAGER environment variable to specify the package manager:

ZBPACK_PYTHON_PACKAGE_MANAGER=pipenv

The value should be one of pip, pipenv, poetry, pdm, rye, or uv.

Laravel Django