Skip to content

Basics

Bound scripts and standalone scripts

Every Apps Script project is either attached to one Google file or standing on its own. The choice decides how your code reaches your data, who can see it, and where you find it later.

1 of 6

A bound script belongs to one file

When you open a spreadsheet and choose Extensions > Apps Script, the project you get is container bound. Bound means it is part of that spreadsheet, the way a comment is part of it. The same is true of a Doc, a Form, or a Slides deck.

Because the project belongs to the file, it has a shortcut to it. SpreadsheetApp.getActiveSpreadsheet() returns that spreadsheet with no id and no setup. In a Doc it is DocumentApp.getActiveDocument(), and in a Form it is FormApp.getActiveForm().

A bound project travels with the file. Copy the spreadsheet and the copy has its own copy of the code. Move the file to another folder and the code goes along. Put the file in the trash and the code goes to the trash with it.

  • Custom menus and simple triggers such as onOpen and onEdit only make sense here, because there is a file to attach them to.
  • Custom spreadsheet functions that you type into a cell must live in the bound project of that spreadsheet.
  • The project does not appear in your Drive as a separate file.

2 of 6

A standalone script belongs to nothing

A project you create at script.google.com with New project is standalone. It sits in your Drive as its own file, like a document does, and it is not attached to any spreadsheet.

A standalone project has no active spreadsheet, so getActiveSpreadsheet has nothing to return. You name the file you want instead. SpreadsheetApp.openById takes the long id from the middle of the spreadsheet URL, and SpreadsheetApp.openByUrl takes the whole address.

The id is the part of the address between /d/ and /edit. Copy it out of the browser bar and paste it in place of the placeholder below.

Open a spreadsheet by id from a standalone project 
function logSpreadsheetName() {
  const spreadsheetId = 'PASTE_THE_ID_FROM_YOUR_SPREADSHEET_URL';
  const spreadsheet = SpreadsheetApp.openById(spreadsheetId);
  const firstSheet = spreadsheet.getSheets()[0];
  Logger.log('Opened ' + spreadsheet.getName() + ', first tab ' + firstSheet.getName() + '.');
}

3 of 6

Which one to choose

Choose bound when the code is about one file and the people who use that file. A menu for your team's tracker, a timestamp that fills in when somebody edits a row, a custom function for one workbook. Anyone who can edit the file can run the code from the menu without hunting for a project.

Choose standalone when the code is about several files, or about no file at all. A nightly job that reads three spreadsheets, a script that files Gmail attachments into Drive, a piece of code you want to reuse across projects as a library.

When you are unsure, start bound. It is the shorter path, and you can move the code into a standalone project later by pasting it and swapping getActiveSpreadsheet for openById.

4 of 6

Finding your scripts again

Go to https://script.google.com/home. That page lists your projects, both kinds together, most recent first. Bound projects show the name of the file they belong to, so you can tell them apart.

You can also reach a bound project the way you made it, through Extensions > Apps Script on the file. That is often faster when you already have the file open.

Standalone projects appear in Drive too. Search Drive for the project name, or filter by the Google Apps Script type.

5 of 6

Sharing, and who can read the code

A bound project is shared with the file. People with access to view, comment on, or edit the spreadsheet can view its source, including any address or setting you typed into the code. Someone allowed to copy the file gets a copy of the code too.

A standalone project is shared like any Drive file, with its own list of people. Sharing the spreadsheet it reads does not share the code, and sharing the code does not share the spreadsheet.

Either way, sharing the code is not the same as sharing your approvals. When somebody else runs it, they see the authorization dialog themselves and the code acts as them, on the files they can already reach.

  • Keep passwords, API keys, and other confidential values out of a bound project when the file is shared with people who must not see them.
  • Use PropertiesService for settings you do not want sitting in the code.
  • Use a standalone project with its own sharing list when the code itself needs a separate confidentiality boundary.

6 of 6

Moving code between the two

There is no button that converts one into the other. You copy the text of your functions into a project of the other kind and adjust the first line or two.

Going from bound to standalone, replace SpreadsheetApp.getActiveSpreadsheet() with SpreadsheetApp.openById(id) and put the id in a named constant at the top. Going the other way, replace openById with getActiveSpreadsheet and delete the id.

Two things do not move. Simple triggers such as onEdit and custom functions used in cells only work in the bound project of that file. Installable triggers are not copied either, so create them again in the new project and approve the access once.

Remember

The short version

  • A bound project is created from Extensions > Apps Script, belongs to one file, and can call getActiveSpreadsheet.
  • A standalone project is created at script.google.com and reaches files with openById or openByUrl.
  • Bound code is visible to people who can view the file, and a permitted copy includes the code, so keep confidential values out of it.
  • https://script.google.com/home lists both kinds of project in one place.
  • Menus, simple triggers, and custom cell functions need a bound project.
SpreadsheetApp.SpreadsheetSpreadsheetApp.SheetDocumentApp.DocumentFormApp.Form

Keep going

Put it to work

All basics