|---|---|
| **Select language:** | [Node.js](https://firebase.google.com/docs/functions/handle-dependencies.md.txt#nodejs) [Python](https://firebase.google.com/docs/functions/handle-dependencies.md.txt#python) |

A Cloud Functions function can use external modules and local dependencies.
How you specify and manage dependencies depends on your runtime language.

## Node.js

A function is allowed to use external Node.js modules as well as local
data. Dependencies in Node.js are managed with [npm](https://docs.npmjs.com/) and expressed in a
metadata file called [`package.json`](https://docs.npmjs.com/files/package.json). The Cloud Functions
Node.js runtimes support installing using [npm](https://docs.npmjs.com/),
[yarn](https://yarnpkg.com/en/), or [pnpm](https://pnpm.io/).

To specify a dependency for your function, add it to your `package.json` file.

> [!NOTE]
> **Note:** If a `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml` file is found within your project, that lock file will be respected when dependencies are installed using `npm ci`, `yarn install` or `pnpm install`.

In this example, a dependency is listed in the `package.json` file:

```javascript
{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}
```

The dependency is then imported in the function:

### JavaScript

```javascript
const onRequest = require("firebase-functions/https");
const escapeHtml = require("escape-html");

// Return a greeting with the input HTML-escaped.
exports.hello = onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);
});
```

### TypeScript

```typescript
import { onRequest } from "firebase-functions/https";
import * as escapeHtml from "escape-html";

// Return a greeting with the input HTML-escaped.
export let hello = onRequest((req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || "World")}!`);
});
```

### Including local Node.js modules

You can also include local Node.js modules as part of your function. You can
achieve this by declaring your module in `package.json` using the
[`file:` prefix](https://docs.npmjs.com/files/package.json#local-paths). In the
following example, `mymodule` refers to your module name and `mymoduledir` is
the directory containing your module:

```javascript
{
  "dependencies": {
    "mymodule": "file:mymoduledir"
  }
}
```

The code for this local module should be stored somewhere other than the
`node_modules` folder within your function's root directory.

> [!NOTE]
> **Note:** The Firebase CLI ignores the local `node_modules` folder when deploying your function.

#### Additional steps for TypeScript

TypeScript helps you most when you use libraries that have type information.
This lets TypeScript catch syntax errors and lets editors give you better
autocomplete suggestions. Some libraries, like `firebase-admin` and
`firebase-functions`, ship with TypeScript definitions included.

Many libraries do not provide their own TypeScript definition. The
[DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) project
provides community-maintained definitions for the most popular node libraries.
DefinitelyTyped publishes these definitions under the same NPM package name, but
inside the "@types" organization. For example, you can install the type
information for the `uuid` library with the following:

    npm install @types/uuid

As you become more familiar with TypeScript, you might find yourself combining
both installs:

    npm install uuid @types/uuid

Type dependencies should be the same kind as the library dependency. For
example, you should not save `uuid` as a normal dependency and `@types/uuid` as
a dev dependency or peer dependency.

### Loading Node.js modules

Use the Node.js
[`require()`](https://nodejs.org/api/modules.html#modules_require)
function to load any Node.js module you have installed. You can also use the
`require()` function to import local files you deploy alongside your function.

If you are writing functions in TypeScript, use the
[`import`](https://www.typescriptlang.org/docs/handbook/modules.html#import)
statement in the same way to load any Node.js module you have installed.

### Using private modules

You can use a [private npm module](https://docs.npmjs.com/private-modules/intro) by providing settings for authenticating with
the registry in a `.npmrc` file in the function's directory. If you're using
Yarn v2 or higher as your package manager, this file is named
`.yarnrc.yml`.

#### Private modules from Artifact Registry

An [Artifact Registry Node.js package repository](https://docs.cloud.google.com/artifact-registry/docs/nodejs/store-nodejs)
can host private modules for your function. When you deploy a Google Cloud Functions
function, the build process automatically generates Artifact Registry credentials
for the [Cloud Build service account](https://docs.cloud.google.com/build/docs/cloud-build-service-account).
You only need to list the Artifact Registry repository in your `.npmrc` without
generating additional credentials. For example:

    @SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
    //REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true

This approach also works for the Yarn v1 package manager.
If you're using Yarn v2 or higher, you only need to list the Artifact Registry
repository in your `.yarnrc.yml` without additional credentials.
For example:

    npmScopes:
      SCOPE:
        npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
        npmAlwaysAuth: true

#### Private modules from other repositories

The [npm documentation](https://docs.npmjs.com/getting-started/working_with_tokens) explains how to create custom read-only
access tokens. We discourage using the `.npmrc` file created in the home
directory because it contains a read-write token. Write permissions are not
required during deployment, and could pose a security risk.

Do not include the `.npmrc` file if you're not using private repositories,
as it can increase the deployment time for your functions.

> [!NOTE]
> **Note:** If you're using any custom permissions (such as those necessary for [VPC](https://docs.cloud.google.com/run/docs/configuring/connecting-vpc)), make sure that you explicitly allow your functions to access the target private repository.

##### File format

If you're using an `.npmrc` file to set a custom auth token, it should include
the line shown below.

    //REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN

Replace:

- <var translate="no">REGISTRY_DOMAIN</var>: the domain name of your private npm registry. If your repository is hosted with `npmjs.org`, set this field to `registry.npmjs.org`.
- <var translate="no">AUTH_TOKEN</var>: the authorization token for your npm registry.
  This can either be the literal text value of the token or the text string
  `${NPM_TOKEN}`, which `npm` replaces with the actual token value from the
  environment.

  You can set the `$NPM_TOKEN` environment variable with the
  [`--set-build-env-vars`](https://docs.cloud.google.com/run/docs/configuring/services/environment-variables)
  argument to your
  [`gcloud functions deploy`](https://docs.cloud.google.com/sdk/gcloud/reference/functions/deploy) command.
  See the [NPM tutorial on private modules](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow#create-and-check-in-a-project-specific-npmrc-file)
  for more details of the NPM auth token.

*** ** * ** ***

## Python

There are two ways to specify dependencies for Cloud Functions written in
Python: using the [pip](https://pip.pypa.io/en/stable/) package manager's
`requirements.txt` file or packaging local dependencies alongside your function.

Dependency specification using the Pipfile/Pipfile.lock standard is
not supported. Your project should not include these files.

### Specifying dependencies with pip

Dependencies in Python are managed with pip and expressed in a metadata file
called
[`requirements.txt`](https://pip.pypa.io/en/stable/user_guide/#requirements-files).
This file must be in the same directory as the `main.py` file that contains your
function code.

When you deploy or redeploy your function, Cloud Functions
uses pip to download and install the latest version of your
dependencies as declared in the `requirements.txt` file.
The `requirements.txt` file contains one line per package. Each line contains
the package name, and optionally, the requested version. For more details, see
the [`requirements.txt`
reference](https://pip.pypa.io/en/stable/user_guide/#requirements-files).

To prevent your build from being affected by dependency version changes,
consider pinning your dependency packages to a specific version.

The following is an example `requirements.txt` file:

```
functions-framework
requests==2.20.0
numpy
```

### Packaging local dependencies

You can also package and deploy dependencies alongside your function. This
approach is useful if your dependency is not available via the pip
package manager or if your Cloud Functions environment's internet
access is restricted.

> [!NOTE]
> **Note:** You can still use a `requirements.txt` file to specify additional dependencies you haven't packaged alongside your function.

For example, you might use a directory structure
such as the following:

```
myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py
```

You can then import the code as usual from `localpackage` using the following
`import` statement.

```py
# Code in main.py
from localpackage import script
```

Note that this approach will *not* run any `setup.py` files. Packages with those
files can still be bundled, but may not run correctly on Cloud Functions.