Python 2.7 has reached end of supportand will bedeprecatedon January 31, 2026. After deprecation, you won't be able to deploy Python 2.7applications, even if your organization previously used an organization policy tore-enable deployments of legacy runtimes. Your existing Python2.7 applications will continue to run and receive traffic after theirdeprecation date. We recommend thatyoumigrate to the latest supported version of Python.

queue.yaml Reference

Region ID

TheREGION_ID is an abbreviated code that Google assignsbased on the region you select when you create your app. The code does notcorrespond to a country or province, even though some region IDs may appearsimilar to commonly used country and province codes. For apps created after February 2020,REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn moreabout region IDs.

Thequeue.yaml configuration file is used to create and configure almost allof the task queues (push orpull)your app uses. All App Engine apps come withan automatically preconfigured push queue nameddefault. Although you do notcreate thedefault queue yourself, you can add other queues or change theconfiguration of thedefault queue using thequeue.yaml file.

To configure push queues, you can use eitherqueue.yaml orQueue Management methods from Cloud Tasks, butnot both at the same time. Mixing thequeue.yaml upload method with Queue Management methods can produce unexpectedresults and is not recommended.

To configure pull queues, you must use thequeue.yaml file.

Caution: Uploading aqueue.yaml file via the gcloud CLI below version332.0.0 uses a deprecated interface to the service. Starting on2022-09-20, attempts to use the upload method can fail withserver errors. To resolve this, make sure the Cloud Tasks API is enabledin your project and your gcloud CLI is updated to at least version332.0.0.

Example

The following a basic example that defines a named queue and overrides thedefault processing rate:

queue:-name:my-push-queuerate:1/s

The following is a more complex example of aqueue.yaml configuration thatdemonstrates setting up the number of task tries and modifying the default processing rate.

queue:-name:fooqueuerate:1/sretry_parameters:task_retry_limit:7task_age_limit:2d-name:barqueuerate:1/sretry_parameters:min_backoff_seconds:10max_backoff_seconds:200max_doublings:0-name:bazqueuerate:1/sretry_parameters:min_backoff_seconds:10max_backoff_seconds:200max_doublings:3

Syntax

Thequeue.yaml file is a YAML file whose root directive isqueue.This directive contains zero or more named queues. Each queue definition canspecify the following elements:

ElementDescription
bucket_size (push queues)

Optional. A task queue uses thetoken bucket algorithm to control the rate of task execution. Each named queue has a token bucket that holds tokens, up to the maximum specified by thebucket_size value. Each time your application executes a task, a token is removed from the bucket. You continue processing tasks in the queue until the queue's bucket runs out of tokens. App Engine refills the bucket with new tokens continuously based on the rate that you specified for the queue.

The bucket size limits how fast the queue is processed when many tasks are in the queue and the rate is high. The maximum value for bucket size is 500. This allows you to have a high rate so processing starts shortly after a task is enqueued, but still limit resource usage when many tasks are enqueued in a short period of time.

If you don't specifybucket_size for a queue, the default value is 5. We recommend that you set this to a larger value because the default size might be too small for many use cases. For example, you could determine your bucket size based on the processingrate.

For more information on this element, see the comparative description ofmax_burst_size

in the Cloud Tasks API reference.
max_concurrent_requests (push queues)

Optional. Sets the maximum number of tasks that can be executed simultaneously from the specified queue. The value is an integer. By default, the limit is 1000 tasks per queue. The upper recommended limit is 5000 tasks per queue. Note that queues may slowly ramp up when they are first created or if they have been idle for a while.

Restricting the number of concurrent tasks gives you more control over the queue's rate of execution and can prevent too many tasks from running at once. It can also prevent datastore contention and make resources available for other queues or online processing.

For more information on this element, see the comparative description ofmax_concurrent_dispatches in the Cloud Tasks API reference.

mode

Optional. Identifies the queue mode. This setting defaults topush, which identifies a queue as apush queue. If you wish to usepull queues, set the mode topull.

name

Required. The name of the queue. This is the name you specify when you callQueueFactory.getQueue().

A queue name can contain uppercase and lowercase letters, numbers, and hyphens. The maximum length for a queue name is 100 characters.

All apps have a push queue named default. This queue has a preset rate of 5 tasks per second. Note that this default queue doesn't display in theGoogle Cloud console until the first time it is used or configured. You can configure the default queue, including changing the default rate, by defining a queue named `default` in yourqueue.yaml file.

rate (push queues)

Required. How often tasks are processed on this queue. The value is a number followed by a slash and a unit of time, where the unit iss for seconds,m for minutes,h for hours, ord for days. For example, the value5/m says tasks will be processed at a rate of 5 times per minute. The maximum value forrate is500/s.

If the number is0 (such as0/s), the queue is considered "paused," and no tasks are processed.

For more information on this element, see the comparative description ofmax_dispatches_per_second in the Cloud Tasks API reference.

retry_parameters

Optional. Configures retry attempts for failed tasks in push queues. This addition allows you to specify the maximum number of times to retry failed tasks in a specific queue. You can also set a time limit for retry attempts and control the interval between attempts.

The retry parameters can contain the following subelements:

task_retry_limit
The number of retries. For example, if0 is specified and the taskfails, the task is notretried at all. If1 is specified and the taskfails, the task is retried once. If this parameter is unspecified, the task is retried indefinitely. Iftask_retry_limit is specified withtask_age_limit, the task is retried until both limits are reached.
task_age_limit (push queues)
The time limit for retrying a failed task, measured from when the task was first run. The value is a number followed by a unit of time, where the unit iss for seconds,m for minutes,h for hours, ord for days. For example, the value5d specifies a limit of five days after the task's first execution attempt. If this parameter is unspecified, the task is retried indefinitely. If specified withtask_retry_limit, App Engine retries the task until both limits are reached.
min_backoff_seconds (push queues)
The minimum number of seconds to wait before retrying a task after it fails. The default value is0.1.
max_backoff_seconds (push queues)
The maximum number of seconds to wait before retrying a task after it fails. The default value is3600.
max_doublings (push queues)
The maximum number of times that the interval between failed task retries will be doubled before the increase becomes constant. The constant is:2**max_doublings * min_backoff_seconds. The default value is16.
target (push queues)

Optional. A string naming a service/version, a frontend version, or a backend, on which to execute all of the tasks enqueued onto this queue. The default value is the empty string.

The string is prepended to the domain name of your app when constructing the HTTP request for a task. For example, if your app ID ismy-app and you set the target tomy-version-dot-my-service, the URL hostname will be set tomy-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com.

If target is unspecified, then tasks are invoked on the same version of the application where they were enqueued. So, if you enqueued a task from the default application version without specifying a target on the queue, the task is invoked in the default application version. Note that if the default application version changes between the time that the task is enqueued and the time that it executes, then the task will run in the new default version.

If you are using services along with adispatch file, your task's HTTP request might be intercepted and re-routed to another service.

The following elements can be specified for all queues within an app:

ElementDescription
total_storage_limit

Optional. A string that overrides the default quota storage limit that is available for taskqueue storage (100M). For example:

total_storage_limit:1.2Gqueue:-name:fooqueue

This quota is part of the application's total storage quota (including the datastore and blobstore quota).

If no suffix is specified, the number that you specify is interpreted as bytes. The following suffixes are supported:

  • B (bytes)
  • K (kilobytes)
  • M (megabytes)
  • G (gigabytes)
  • T (terabytes)

Iftotal_storage_limit exceeds the total disk storage that is available to an application, the limit is capped at the available storage.

Deploying the queue configuration file

Thequeue.yaml file should reside in the root directory or in thedirectory that defines the default service.

To deploy the queue configuration file, run the following command:

gcloudappdeployqueue.yaml

Deleting queues

To delete a queue:

  1. Remove the queue definition from yourqueue.yaml file.

  2. Upload the change to yourqueue.yaml file.

    gcloud app deploy queue.yaml

  3. Delete the queue in the Google Cloud console, select the queue and clickDelete queue:

    Go to the Task queues page

If you delete a queue from the Google Cloud console, you must wait 7 daysbefore recreating with the same name.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.