If you are writing a custom script to organize thousands of documents within Google Workspace, you might assume that “moving” a file via the Google Drive API requires downloading it to your local server and uploading it to a new location. Fortunately, the Google Drive API treats files more like database records than physical objects. Because a single file in Google Drive can exist in multiple folders simultaneously (or no folders at all), “moving” a file simply involves updating the metadata to remove the old parent folder ID and add the new parent folder ID.
Understanding the Folder Architecture
In a traditional Windows or Linux file system, a file exists within a rigid hierarchical path (e.g., C:\Marketing\Report.pdf). If you move the file, the path fundamentally changes.
In Google Drive, every file has a unique, permanent alphanumeric ID (e.g., 1aB2c3D4e5F6g7H8i9J0). The folders are also just files that happen to have the MIME type application/vnd.google-apps.folder. When you place a document inside a folder, you are merely appending that folder’s ID to the document’s parents array.
The API Endpoint
To move a file, you do not use a dedicated “move” command. Instead, you use the standard Files: update method.
The HTTP request looks like this:
PATCH https://www.googleapis.com/drive/v3/files/[FILE_ID]The Critical Parameters: addParents and removeParents
To execute the move, you must pass two specific query parameters in the URL of your PATCH request. You do not modify the JSON body of the file; you only alter the query string.
addParents: A comma-separated list of the new folder IDs where the file should be placed.removeParents: A comma-separated list of the old folder IDs where the file currently resides.
If you only use addParents, the file will exist in both the old folder and the new folder simultaneously (creating a shortcut/alias). To execute a true “move,” you must explicitly remove the old parent.
Example using Python
Here is how you execute a move using the official Google API Client Library for Python. In this example, we have already authenticated and built the service object.
# The ID of the file you want to move
file_id = '1abc123XYZ'
# The ID of the folder the file is currently sitting in
old_folder_id = '9def987UVW'
# The ID of the destination folder
new_folder_id = '5ghi546RST'
# Execute the API call
moved_file = service.files().update(
fileId=file_id,
addParents=new_folder_id,
removeParents=old_folder_id,
fields='id, parents'
).execute()
print(f"File moved successfully. New parents: {moved_file.get('parents')}")Important Considerations for Shared Drives
The process becomes slightly more complex if you are moving files into, out of, or within a Shared Drive (formerly Team Drives), rather than a personal “My Drive”.
If the file is interacting with a Shared Drive, you must append an additional query parameter to your request: supportsAllDrives=true. If you omit this flag, the API will return a 404 error, pretending the Shared Drive folders do not exist, as a safeguard against legacy code accidentally corrupting Shared Drive permissions.
moved_file = service.files().update(
fileId=file_id,
addParents=new_folder_id,
removeParents=old_folder_id,
supportsAllDrives=True,
fields='id, parents'
).execute()By simply manipulating the parents array, your scripts can instantly reorganize millions of files without ever transferring a single byte of actual file data over the network.