Install & Compatibility
Where this runs
tested against v2.20.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.95 runs
installs and imports cleanly · install 0.0s · import 1.634s · 69.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 1.154s · 68MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CloudSchedulerClient
✓ from google.cloud import scheduler_v1
✗ from google.cloud.scheduler import CloudSchedulerClient
The client class is nested under the `scheduler_v1` module, representing the v1 API.
CloudSchedulerClient (v1beta1)
✓ from google.cloud import scheduler_v1beta1
Use this import for the beta version of the API. Generally, `v1` is preferred for production unless specific beta features are required.
This quickstart demonstrates how to create a simple Cloud Scheduler job that triggers an HTTP endpoint every hour using the `scheduler_v1` API. Ensure your `GCP_PROJECT_ID`, `GCP_LOCATION_ID`, `SCHEDULER_JOB_NAME`, and `SCHEDULER_TARGET_URL` environment variables are set or replaced in the code. Authentication is handled automatically via Application Default Credentials if running in a Google Cloud environment or with `gcloud auth application-default login` locally.
import os
from google.cloud import scheduler_v1
project_id = os.environ.get('GCP_PROJECT_ID', 'your-project-id')
location_id = os.environ.get('GCP_LOCATION_ID', 'us-central1') # e.g., 'us-central1'
job_name = os.environ.get('SCHEDULER_JOB_NAME', 'my-scheduled-job')
target_url = os.environ.get('SCHEDULER_TARGET_URL', 'https://your-http-endpoint.cloudfunctions.net/myFunction')
# Initialize a client
client = scheduler_v1.CloudSchedulerClient()
# Construct the full resource name of the parent of the job
parent = client.location_path(project_id, location_id)
# Construct the job body
job = scheduler_v1.Job()
job.name = client.job_path(project_id, location_id, job_name)
job.description = 'My first Cloud Scheduler job (Python client)'
job.schedule = '0 * * * *' # Run every hour
job.time_zone = 'America/Los_Angeles'
# Configure an HTTP target
http_target = scheduler_v1.HttpTarget()
http_target.uri = target_url
http_target.http_method = scheduler_v1.HttpMethod.POST
job.http_target = http_target
# Create the job
try:
response = client.create_job(parent=parent, job=job)
print(f'Created job: {response.name}')
except Exception as e:
print(f'Error creating job: {e}')
# To delete the job (uncomment to run)
# try:
# client.delete_job(name=response.name)
# print(f'Deleted job: {response.name}')
# except Exception as e:
# print(f'Error deleting job: {e}')
Debug
Known issues
breakingThe library explicitly requires Python 3.9 or newer. Running on older Python versions (3.8 or below) will result in installation failures or runtime errors.fixUpgrade your Python environment to 3.9 or higher. For example, using `pyenv` or updating your system's Python installation.
affects: <2.19.0 (earlier versions might support older Python, but 2.19.0+ requires >=3.9)
gotchaAuthentication is a common source of errors. The client library uses Application Default Credentials (ADC) by default, but it must be correctly configured in your environment (e.g., via `gcloud auth application-default login` locally, or by attaching a service account to your compute resource in GCP). Incorrect permissions for the executing service account (e.g., lacking `roles/cloudscheduler.admin` or permissions to invoke the target) will lead to 401/403 errors.
gotchaGoogle Cloud client libraries often offer multiple API versions (e.g., `v1`, `v1beta1`). While `v1beta1` might contain newer features, it is a beta API and not guaranteed to be stable or backward compatible. Always prefer `v1` for production workloads to ensure stability and avoid unexpected breaking changes.fixUse `from google.cloud import scheduler_v1` for stable production code. Only use `scheduler_v1beta1` if you explicitly require a beta feature and understand the implications.
affects: All versions where `v1beta1` exists alongside `v1`
gotchaIncorrectly configuring job targets (HTTP, Pub/Sub, App Engine) can lead to silent failures or unexpected behavior. Pay close attention to `uri`, `http_method`, `headers`, `schedule` (cron format), and `time_zone`. For HTTP targets, ensure the `Content-Type` header is explicitly set if your endpoint expects a specific type, as `application/octet-stream` is a common default.
gotchaCloud Scheduler jobs have a default timeout (e.g., 30 minutes for HTTP targets). If your scheduled task is long-running and exceeds this, Cloud Scheduler will report a failure even if the downstream service eventually succeeds. Also, retry configurations must be carefully tuned to avoid overwhelming the target or incurring excessive costs.
Errors
Common errors & fixes
INVALID_ARGUMENT (often seen with HTTP 400 in logs)
The job configuration, particularly for HTTP targets, contains invalid or improperly formatted data that the target service cannot process (e.g., incorrect URI, missing 'Content-Type' header, or a malformed body payload).
fixEnsure the 'uri', 'http_method', 'headers', and 'body' in your job's 'http_target' configuration precisely match the expectations of the target service. For Cloud Functions/Run, explicitly include `"Content-Type": "application/json"` in headers and an empty JSON body `{}` if no actual payload is needed:
```python
job = {
'http_target': {
'uri': 'https://your-target-url.cloudfunctions.net/your_function',
'http_method': 'POST',
'headers': {
'Content-Type': 'application/json'
},
'body': b'{}' # or json.dumps({'key': 'value'}).encode('utf-8')
},
'schedule': '0 9 * * *',
'time_zone': 'America/Los_Angeles'
}
``` PERMISSION_DENIED (HTTP 403 Forbidden) or URL_ERROR-ERROR_AUTHENTICATION (HTTP 401 Unauthorized)
The service account associated with the Cloud Scheduler job lacks the necessary IAM permissions to invoke its designated target service (e.g., Cloud Run, Cloud Functions, Workflows) or to perform core Cloud Scheduler operations.
fixGrant the appropriate IAM roles to the service account used by the Cloud Scheduler job. Common roles include `roles/cloudscheduler.serviceAgent` for Cloud Scheduler itself and `roles/run.invoker` for Cloud Run targets, or `roles/workflow.invoker` for Cloud Workflows targets. You can do this via the GCP Console or `gcloud` command line:
```bash
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member='serviceAccount:SERVICE_ACCOUNT_EMAIL' \
--role='roles/run.invoker'
``` AttributeError: 'CloudSchedulerClient' object has no attribute 'location_path'
The method `location_path` for constructing resource names has been deprecated or renamed in newer versions of the `google-cloud-scheduler` Python client library.
fixUse `client.common_location_path` instead of `client.location_path`, or construct the parent path string directly as `f"projects/{project_id}/locations/{location_id}"`:
```python
from google.cloud import scheduler_v1
client = scheduler_v1.CloudSchedulerClient()
project_id = 'your-project-id'
location_id = 'your-location-id'
# Option 1: Using common_location_path
parent = client.common_location_path(project_id, location_id)
# Option 2: Constructing the string directly
# parent = f"projects/{project_id}/locations/{location_id}"
# Now use 'parent' in methods like list_jobs or create_job
# for element in client.list_jobs(parent=parent):
# print(element)
``` ModuleNotFoundError: No module named 'google.cloud.scheduler_v1' (or similar for 'google.cloud.scheduler')
The `google-cloud-scheduler` library is not installed in the Python environment, or the Python environment where the code is being run (e.g., local virtual environment, Cloud Run, Cloud Functions) does not have access to the installed package.
fixEnsure the `google-cloud-scheduler` library is installed in your environment. If running locally, activate your virtual environment and run:
```bash
pip install google-cloud-scheduler
```
If deploying to Cloud Run or Cloud Functions, make sure `google-cloud-scheduler` is listed in your `requirements.txt` file.
Upgrade
Version history
2.20.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies
PythonrequiredRequired Python version as specified by the package metadata.