Google Cloud projects form the basis for creating, enabling, and using all Google Cloud services including managing APIs, enabling billing, adding and removing collaborators, and managing permissions for Google Cloud resources.
This page explains how to create and manage Google Cloud projects using the Resource Manager API and the Google Cloud Console.
Before you begin
Read about the project resource in the Resource Hierarchy overview. For guidance on project structure, see Best practices for enterprise organizations.
The following are used to identify your project:
Project name: A human-readable name for your project.
The project name isn't used by any Google APIs. You can edit the project name at any time during or after project creation. Project names do not need to be unique.
Project ID: A customizable unique identifier for your project.
The project ID is a unique, user-assigned ID that can be used by Google APIs. If you do not specify a project ID during project creation, a project ID will be generated automatically.
The project ID must be a unique string of 6 to 30 lowercase letters, digits, or hyphens. It must start with a letter, and cannot have a trailing hyphen. You cannot change a project ID once it has been created. You cannot re-use a project ID that is in use, or one that has been used for a deleted project.
Some words are restricted from use in project IDs. If you use restricted words in the project name, such as
google
orssl
, the generated project ID will not include these words.Project number: An automatically generated unique identifier for your project.
The project number and project ID are unique across Google Cloud. If another user owns a project ID for their project, you won't be able to use the same project ID. You can't reuse the project ID of a deleted project.
When you choose your project ID (or any resource names), don't include any sensitive information in your names.
Creating a project
To create a project, you must have the resourcemanager.projects.create
permission. This permission is included in the Project Creator
roles/resourcemanager.projectCreator
role, which is granted by default to the
entire domain of a new organization and to free trial users. For information on
how to grant individuals the role and limit organization-wide access, see the
Managing Default Organization Roles page.
If you do not specify the parent resource, a parent resource is selected automatically based on the user account's domain.
You can create a new project using the Cloud Console, the
gcloud
command-line tool, or
the projects.create()
method.
Console
To create a new project:
-
Go to the Manage resources page in the Cloud Console.
GO TO THE MANAGE RESOURCES PAGE - On the Select organization drop-down list at the top of the page, select the organization in which you want to create a project. If you are a free trial user, skip this step, as this list does not appear.
- Click Create Project.
- In the New Project window that appears, enter a project name and select a billing account as applicable. A project name can contain only letters, numbers, single quotes, hyphens, spaces, or exclamation points, and must be between 4 and 30 characters.
- Enter the parent organization or folder in the Location box. That resource will be the hierarchical parent of the new project.
- When you're finished entering new project details, click Create.
gcloud
To create a new project, use the
gcloud projects create
command:
gcloud projects create PROJECT_ID
Where PROJECT_ID is the ID for the project you want to create. A project ID must start with a lowercase letter, and can contain only ASCII letters, digits, and hyphens, and must be between 6 and 30 characters.
To create a project with an organization or a folder as parent, use the
--organization
or --folder
flags. As a resource can only have one
parent, only one of these flags can be used:
gcloud projects create PROJECT_ID
--organization=ORGANIZATION_ID
gcloud projects create PROJECT_ID --folder=FOLDER_ID
API
You can't use certain words in the project ID when you create a new project
with the projects.create()
method. Some examples include ssl
and
google
. When you use a restricted word, the request will return with
an INVALID_ARGUMENT
error.
The below request only creates a project, and does not associate it
automatically with a billing account. Use the
projects.updateBillingInfo
method to set or update the billing account associated with a project.
Create Project Request:
POST https://cloudresourcemanager.googleapis.com/v1/projects/
Authorization: *************
Content-Type: application/json
{
"projectId": "our-project-123",
"name": "my project",
"labels": {
"mylabel": "prod"
}
}
Create Project Response:
{
"name": "operations/pc.123456789",
}
Get Operation Request:
GET https://cloudresourcemanager.googleapis.com/v1/operations/pc.123456789
Authorization: *************
Content-Type: application/json
Get Operation Response:
{
"name": "operations/pc.123456789",
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloudresourcemanager.v1.Project",
"projectNumber": "464036093014",
"projectId": "our-project-123",
"lifecycleState": "ACTIVE",
"name": "my project",
"labels": {
"mylabel": "prod"
},
"createTime": "2016-01-07T21:59:43.314Z"
}
}
Python
...
from googleapiclient import discovery
from oauth2client.client import OAuth2Credentials as creds
crm = discovery.build(
'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))
operation = crm.projects().create(
body={
'project_id': flags.projectId,
'name': 'my project'
}).execute()
...
Creating a project using a service account
You can use a service account to automate project creation. Like user accounts,
service accounts can be granted permission to create projects within an
organization. Service accounts are not allowed to create projects outside of an
organization and must specify the parent resource when creating a project.
Service accounts can create a new project using the gcloud
tool or the
projects.create()
method.
Managing project quotas
If you have fewer than 30 projects remaining in your quota, a notification will display the number of projects remaining in your quota on the New Project page. Once you have reached your project limit, to create more projects you must request a project limit increase. Alternatively, you can schedule some projects to be deleted after 30 days on the Manage Resources Page. Projects that users have soft deleted count against your quota. These projects will be fully deleted after 30 days.
To request additional capacity for projects in your quota, see the Request Billing Quota Increase support page. More information about quotas and why they are used can be found at the Free Trial Project Quota Requests support page. For more information about billing reports, see the Billing Reports support page.
Identifying projects
To interact with Google Cloud resources, you must provide the identifying project information for every request. A project is identified by its project ID and project number.
To get the project ID and the project number:
Go to the Dashboard page in the Cloud Console.
Click the Select from drop-down list at the top of the page. In the Select from window that appears, select your project.
The project ID and project number are displayed on the project Dashboard Project info card:

In the above example, the project name is My Sample Project and the project ID is my-sample-project-191923.
Get an existing project
You can get an existing project using the Cloud Console or
the projects.get()
method.
Console
To view a project using the Google Cloud Console:
- Go to the Dashboard page in the Google Cloud Console.
- Click the Select from drop-down list at the top of the page. In the Select from window that appears, select your project.
gcloud
To get the metadata for a project, use the
gcloud projects describe
command:
gcloud projects describe PROJECT_ID
Where PROJECT_ID is the ID of the project you want to view.
API
Request:
GET
https://cloudresourcemanager.googleapis.com/v1beta1/projects/our-project-123
Response:
{
"projectNumber": "464036093014",
"projectId": "our-project-123",
"lifecycleState": "ACTIVE",
"name": "my project",
"labels": {
"mylabel": "prod"
},
"createTime": "2016-01-07T21:59:43.314Z"
}
Python
...
from googleapiclient import discovery
from oauth2client.client import OAuth2Credentials as creds
crm = discovery.build(
'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))
project = crm.projects().get(projectId=flags.projectId).execute()
...
Listing projects
You can list all projects you have access to using the Cloud Console or
the projects.list()
method.
Console
To list projects using the Google Cloud Console:
- Go to the Cloud Console.
- All your projects are listed in the projects drop-down on the top bar. Use the Search projects and folders textbox to filter projects.
- To list all your projects, click Manage Resources. Use the Filter by name, ID, or label textbox to filter your projects.
gcloud
To list all projects accessible by your currently active account, use the
gcloud projects list
command:
gcloud projects list
This command will provide the project ID, name, and project number for every project for which you have Owner, Editor, or Viewer permissions.
You can use the --filter
flag to narrow the results. This flag searches
the project ID, name, and project number, and only returns results where
the filtered term exists:
gcloud projects list --filter=test
The above command will return all projects for which you have Owner, Editor, or Viewer permission for, and also include the word "test" in the name, project ID, or project number fields.
If you specify a filter that has both the parent.type
and
parent.id
fields, then the
resourcemanager.projects.list
permission is checked on the
parent. If the user has this permission, all projects under the parent will
be returned after the remaining filters have been applied.
If the user lacks this permission, then all projects for which
the user has the resourcemanager.projects.get
permission will
be returned after remaining filters have been applied.
If no filter is specified, the call will return projects for which the user
has resourcemanager.projects.get
permissions.
For more information on filter syntax,
see gcloud topic filters
.
API
You can include fields in the body of your request to return specific Project resources that match the filter and for which you've been granted the Owner, Editor, or Viewer roles.
The following code snippet returns the Project resource with the name "project a":
Request:
GET https://cloudresourcemanager.googleapis.com/v1beta1/projects
{
"name": "project a"
}
Response:
{
"projects": [
{
"projectNumber": "951040570662",
"projectId": "google.com:api-project-951040570662",
"lifecycleState": "ACTIVE",
"name": "project a",
"createTime": "2013-11-13T20:31:53.308Z"
}
]
}
The following code snippet returns all Project resources with a red label:
Request:
GET
https://cloudresourcemanager.googleapis.com/v1beta1/projects
{
"labels": {
"color": "red"
}
}
Response:
{
"projects": [
{
"projectNumber": "350831539566",
"projectId": "my-project-b",
"lifecycleState": "ACTIVE",
"name": "project b",
"labels": {
"color": "red"
},
"createTime": "2012-02-18T23:11:57.831Z"
}
]
}
If you specify the parent.type
and parent.id
fields in your request body, then the
resourcemanager.projects.list
permission is checked on the
parent. If the user has this permission, all projects under the parent will
be returned after the remaining filters have been applied.
If the user lacks this permission, then all projects for which
the user has the resourcemanager.projects.get
permission will
be returned after remaining filters have been applied.
If no filter is specified, the call will return projects for which the user
has resourcemanager.projects.get
permissions.
Python
...
from googleapiclient import discovery
from oauth2client.client import OAuth2Credentials as creds
crm = discovery.build(
'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))
filter = "name:project a"
projects = crm.projects().list(filter=filter).execute()
...
The following code snippet lists all projects with a red label:
filter = 'labels.color:red'
projects = crm.projects().list(filter=filter).execute()
Updating projects
You can update projects using the Cloud Console or the
projects.update()
method.
Currently the only fields that can be updated are the project name and labels.
You cannot change the project ID value that you use with the gcloud
command-line tool or API requests. For more information about updating projects,
see the
project API reference page.
Console
To update a project's field using the Cloud Console:
- Open the Settings page in the Google Cloud Console.
- At the top of the screen, click the project selection drop-down list.
- On the Select from window that appears, click the organization drop-down list and then select your organization. If you are a free trial user, skip this step, as the organization list does not appear.
- Select your project from the list that appears.
- To change the project name, edit Project name, then click Save.
- To change labels, click Labels on the left nav. Learn more about Using Labels.
gcloud
To update a project's name or labels, use the
gcloud alpha projects update
command:
gcloud alpha projects update PROJECT_ID
--name=NAME
--update-labels=[KEY=VALUE, ...]
Where:
PROJECT_ID is the ID of the project you want to update.
NAME is the new name you want to assign to the project.
[KEY=VALUE, ...] is a list of the key=value pairs of labels you want to update. If a label already exists, its value is modified. If it does not exist, a new label is created.
For more information and additional flags that can be used with this
command, see the
gcloud
command-line tool SDK.
API
To update a project:
- Get the
project
object usingprojects.get()
method. - Modify the field you want to update.
- Update the
project
object usingprojects.update()
method.
The following code snippet updates the name of the project to "myproject":
Request:
PUT https://cloudresourcemanager.googleapis.com/v1beta1/projects/my-project-123
{
"name": "myproject"
}
Response:
{
"projects": [
{
"projectNumber": "951040570662",
"projectId": "my-project-123",
"lifecycleState": "ACTIVE",
"name": "myproject",
"createTime": "2013-11-13T20:31:53.308Z"
}
]
}
Python
...
from googleapiclient import discovery
from oauth2client.client import OAuth2Credentials as creds
crm = discovery.build(
'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))
project = crm.projects().get(projectId=flags.projectId).execute()
project['name'] = 'myproject'
project = crm.projects().update(
projectId=flags.projectId, body=project).execute()
...
Shutting down (deleting) projects
You can shut down projects using the Cloud Console or the
projects.delete()
method. A project must have a lifecyle state of ACTIVE
to be shut down in
this way.
This method immediately marks a project to be deleted. A project that is marked for deletion is not usable. If the project has a billing account associated with it, that association is broken, and will not be reinstated even if the project delete operation is immediately canceled. After approximately 30 days, the project will be fully deleted. To stop this process during the 30-day period, see the steps to restore a project.
At the end of the 30-day period, the project and all of its resources are deleted and cannot be recovered. Until it is deleted, the project will count towards your project quota.
If you have set up billing for a project, it might not be completely deleted until the current billing cycle ends and your account is successfully charged. The number and types of services in use can also affect when the system permanently deletes a project. To learn more about data retention and safe deletion, see How Google retains data we collect.
To shut down a project:
Console
To shut down a project using the Cloud Console:
Open the Settings page (found under IAM & admin) in the Google Cloud Console.
Click Select a project.
Select a project you want to delete, and click Open.
Click Shut down.
Enter the Project ID, then click Shut down.
gcloud
To delete a project, use the
gcloud projects delete
command:
gcloud projects delete PROJECT_ID
Where PROJECT_ID is the ID of the project you want to delete.
API
The following code snippet deletes the specified project:
Request:
DELETE
https://cloudresourcemanager.googleapis.com/v1beta1/projects/my-project-123
Python
...
from googleapiclient import discovery
from oauth2client.client import OAuth2Credentials as creds
crm = discovery.build(
'cloudresourcemanager', 'v1', http=creds.authorize(httplib2.Http()))
project = crm.projects().delete(projectId=flags.projectId).execute()
...
Troubleshooting project deletion
If the process to shut down a project fails, you can find more information at Troubleshooting project deletion.
Restoring a project
Project owners can restore a deleted project within the 30-day recovery period that starts when the project is shut down. Restoring a project returns it to the state it was in before it was shut down. Some resources, such as Cloud Storage or Pub/Sub resources, are deleted before the 30-day period ends, and may not be fully recoverable.
Some services might need to be restarted manually. For more information, see Restarting Google Cloud Services.
You must have the resourcemanager.projects.undelete
permission on the project
you wish to restore. To restore a project:
Console
To view the project in the Cloud Console, you need the following permissions:
resourcemanager.projects.list
resourcemanager.folders.list
resourcemanager.projects.get
To restore a project using the Cloud Console:
Go to the Manage resources page in the Google Cloud Console.
In the Project picker at the top of the page, select your organization.
Below the list of organizations, folders, and projects, click Resources pending deletion.
Check the box for the project you want to restore, then click Restore. In the dialog that appears, confirm that you want to restore the project.
gcloud
To restore a project, use the
gcloud projects undelete
command:
gcloud projects undelete PROJECT_ID
Where PROJECT_ID is the project ID or project number of the project you want to restore.
API
The following code snippet restores the specified project:
Request:
POST
https://cloudresourcemanager.googleapis.com/v1/projects/my-project-123:undelete
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Get started for free