Skip to navigation

Use Postman elements as dependencies

View as Markdown

A dependency is a collection, environment, or mock from another workspace that you add to your local workspace so you can develop against it. For example, if your service calls a payments API that another team owns, you can add that team’s collection or mock as a dependency instead of exporting it and keeping your copy up to date by hand.

A dependency is a read-only copy of its source element. It has its own icon in the sidebar. You can’t edit a dependency, but you can update it to pull the latest changes from its source, or delete it.

In the Postman desktop app, dependencies are only available in local mode. To manage them in the app, connect the workspace to your local Git repo. You can’t add an element as a dependency to the workspace it’s already in.

If you’re on a Postman Enterprise plan, Use / Fork isn’t available. You can add dependencies from your workspace with Use resources or import instead.

Add a collection from its source workspace

To add a collection as a dependency from the workspace it’s in, do the following:

  1. In the Postman desktop app, select the collection in the sidebar.
  2. Click Use in the upper right of the workbench. Or, hover over the collection in the sidebar, click Options icon View more actions, and then select Use / Fork.
  3. Select the workspace to add the collection to. If the workspace isn’t connected to a Git repo, click Connect Git to connect it.
  4. Under Use as, select Dependency.
  5. Click Use Collection. Postman adds the collection to the workspace as a dependency.

Add a dependency from your workspace

You can also find and add collections, environments, and mocks from your local workspace. When you add a collection this way, Postman also adds the environments pinned to it as dependencies.

To add a dependency from your workspace, do the following:

  1. In the Postman desktop app, open the local workspace you want to add the dependency to.
  2. Click Import icon Use resources or import in the sidebar, and then select the Resources tab.
  3. Search for the element you want to use. To narrow the results, click Private Network, Team, or Public Network, or use the Type and Workspace filters.
  4. Select one or more elements, and then click Add Dependency.

Manage dependencies

To pull the latest changes from a dependency’s source, hover over the dependency in the sidebar, select Options icon View more actions, and then select Update. When you update a collection, Postman also updates the environments pinned to it. To remove the dependency, select Delete instead.

You can also manage all of a workspace’s dependencies at once. Click Import icon Use resources or import in the sidebar, and then select the Resources tab. The In this Workspace section lists the collections, environments, and mocks the workspace uses as dependencies. From the list, you can update or delete a dependency, or click Update All to pull the latest changes for every dependency.

Share dependencies with your team

Postman records each dependency in the dependencies section of your project’s .postman/resources.yaml file, mapped to the ID of its source element. When you commit and push this file, teammates who pull your changes get the same dependencies in their local workspace.

Postman saves the dependency’s files in the postman/.dependencies/ directory of your project and adds that directory to your .gitignore file, so the files aren’t committed to your repo. The resources.yaml file only keeps a small record of each dependency.

After a teammate pulls your changes, they need to install the dependencies to download them to their local project. To install dependencies, do the following:

  1. In the Postman desktop app, open the local workspace.
  2. Click Import icon Use resources or import in the sidebar, and then select the Resources tab.
  3. In the In this Workspace section, dependencies that aren’t downloaded yet are marked Not installed. Click Install next to a dependency, or click Install (n) to install all of them at once, where n is the number of dependencies to install.

You can also add, install, update, and remove dependencies from the command line. The Postman desktop app and the Postman CLI use the same resources.yaml file, so a dependency you add with one appears in the other. For more information, see Postman CLI dependency commands.

Dependencies are useful for local workflows that rely on services owned by other teams. For example, a simulation in local mode can use mocks that you add as dependencies to stand in for those services.