Can I use an orb within an orb?

Overview

It depends on what you mean by “within an orb.”

Yes for registry orbs (public or private) authored with the Orb Development Kit: you can declare an orbs: section in @orb.yml and build your orb from other orbs.
No for inline orbs: one inline orb cannot reference another inline orb in the same config.yml.
At the project level, you normally combine multiple orbs in .circleci/config.yml; that is the usual way to use more than one orb in a pipeline.

Registry orb dependencies are resolved when you publish the orb, not on every pipeline run. Published orb versions are immutable; dependent orb content is included in the packaged orb at that version.

Using other orbs inside a registry orb (supported)

When you author a registry orb with the Orb Development Kit, list dependencies in src/@orb.yml:

orbs:
  node: circleci/node@5.0

You can then reference that orb’s commands, jobs, and executors in your orb, for example:

executors:
  my-executor: node/default

commands:
  my-command: node/install-packages

jobs:
  my-job:
    executor: my-executor
    steps:
      - checkout
      - my-command

See the Orb Template and Using orbs within your orb and register-time resolution in the docs.

Register-time resolution (important)

When you publish a registry orb, CircleCI resolves every orb listed in @orb.yml at publish time and bakes that resolved configuration into the new orb version.

Example:

You publish foo/bar@1.2.3 with biz/baz@volatile in @orb.yml.
At publish time, volatile resolves to whatever biz/baz version is current (say 2.1.0).
Consumers of foo/bar@1.2.3 always get that resolved content.
If biz/baz later publishes 3.0.0, users on foo/bar@1.2.3 do not pick that up until you publish a new version of foo/bar.

Pin dependency versions (for example circleci/node@5.0.1 instead of @volatile) when you want predictable, reviewable releases.

This is not dynamic nesting at runtime. Pipelines do not import a chain of live orbs through your published orb; they use the single packaged orb version you published.

What is not supported

Inline orbs cannot reference other inline orbs

Inline orbs are defined inside .circleci/config.yml. They use a closed scope: an inline orb cannot reference another inline orb in the same file.

An inline orb can import a registry or URL orb and use its commands, jobs, and executors. See Create an inline orb – importing other orbs.

You do not nest orbs in project config

In a project’s config.yml, you declare orbs side by side and orchestrate them in workflows. You do not define an orbs: block inside another orb’s definition in that file (except when defining an inline orb’s own orbs: stanza, as above).

version: 2.1

orbs:
  orb-one: namespace/orb-one@1.0.0
  orb-two: namespace/orb-two@2.0.0

workflows:
  main:
    jobs:
      - orb-one/some-job
      - orb-two/another-job

Private registry orbs

Private registry orbs in your organization can depend on other orbs in @orb.yml, including other private orbs in the same organization, subject to these limits:

Cross-organization: A private orb from org A cannot be used in org B’s pipelines, including as a dependency of another orb.
Validation: circleci config validate may not resolve private orbs unless you use org context. See How to validate a config that uses private Orbs.
Version pins: Use explicit versions for private dependencies when you publish. Loose pins (for example @0 or @volatile) can cause publish failures if the depended-on orb does not expose the command or job you reference at the resolved version.

Recommended patterns

Goal	Approach
Build a reusable package that wraps public or private registry orbs	`orbs:` in `@orb.yml`, compose commands/jobs/executors, publish with the CLI
Use several orbs in one pipeline	List each orb in the project `config.yml` and call them from workflows
Reuse config in one repo only	Inline orb; import registry/URL orbs if needed; do not nest inline inside inline
Share logic without duplicating YAML	Prefer a focused registry orb, or compose registry orbs at publish time

Additional notes

Immutability: Published registry orb versions cannot be changed. To pick up a new dependency version, publish a new semver version of your orb.
Composition: The orb ecosystem is designed so dependencies are explicit at publish time (for registry orbs) and at project config (for consumers), which avoids hidden dependency chains at runtime.