kairo.toml manifest, restore them with Forge, and lock them to exact resolved versions in a forge.lock file that you commit to source control. This model keeps builds reproducible across machines and over time — every developer and every CI run sees exactly the same dependency graph.
Declaring dependencies
Add a[dependencies] section to your kairo.toml and list each dependency as a Name = "version" pair. Versions must be exact — Kairo does not support version ranges, wildcards, or the latest keyword.
Declaring a dependency in
[dependencies] makes it available for import in
your source files. Transitive dependencies are not implicit source
imports. If your code directly uses a module from a package that one of
your dependencies depends on, you must add that package to your own
[dependencies] section and import it explicitly.Restoring dependencies with forge restore
After adding or changing entries in [dependencies], run forge restore to resolve the full dependency graph and write the lockfile:
forge.lock. Subsequent commands (forge check, forge build, forge test) all read from forge.lock rather than re-resolving the graph, so the lockfile must exist before you build.
The lockfile: forge.lock
forge.lock is the canonical record of every package in your resolved build graph — direct dependencies, transitive dependencies, and their exact versions. It is generated by forge restore and read by every subsequent Forge command.
Always commit forge.lock to source control. Committing the lockfile ensures that every developer, every CI job, and every deployment uses an identical dependency graph. Excluding it forces Forge to re-resolve on every fresh clone, which can produce different results if new package versions have been published since you last ran forge restore.
forge clean removes build/ and .forge/ but never deletes
forge.lock. Your lockfile is always safe.Dependency rules
Kairo enforces a strict set of rules on the dependency graph to keep builds deterministic and auditable:Only libraries can be dependencies
Anapplication package is a terminal artifact — it runs, but it is not consumed by other packages. Only packages with kind = "library" may appear in a [dependencies] section.
One version per package name
At most one version of any given package name may appear anywhere in a resolved build graph. If two packages in your dependency tree require different versions of the same library, Forge reports a hard error and refuses to build:Transitive dependencies require explicit imports
Including a library as a dependency does not make its transitive dependencies available for import in your own source. If you call into a type or function that lives in a package your dependency uses internally, you must add that package to your own[dependencies] and import it directly.
Published versions are immutable
Once a version of a package is published to the registry, it cannot be changed. You can publish a new version, but the content of any existing version is fixed. This guarantee is what makes lockfiles meaningful —forge.lock pinning Astra.Data = "1.0.0.0" always refers to exactly the same code.
Understanding version components
When choosing which version of a dependency to declare, use theMajor.Minor.Build.Candidate breakdown as a guide:
Next steps
Forge
Learn all Forge commands, including
forge restore, forge build, and
forge publish.Manifest
Review the full
kairo.toml field reference, including version format
details.