How to Add a Dependency to a Foundry Project

A guide to adding external repositories as dependencies to your Foundry project using forge add, with a real-world example from a Code4rena contest.

When I’m working on a security audit, I often need to add the audited project’s contracts as a dependency to my Foundry fuzzing or testing project. This lets me easily import and interact with the project’s code. This recipe shows you how to do that using forge add.

For example, in the recent Covenant audit from Code4rena, I set up a new Foundry project called covenant-fuzz. The Covenant repo is here.

The Basic Command

The forge add command is used to install one or more dependencies. If you don’t provide any arguments, it will install existing dependencies listed in your foundry.toml or remappings.txt.

To add a new dependency, you provide the GitHub username and project name. You can also specify a tag, branch, or commit hash.

forge add <github-username>/<github-project>@<ref>

You can also give the dependency an alias, which is super useful for keeping your imports clean. The dependency will be installed to lib/<alias>.

forge add <alias>=<github-username>/<github-project>@<ref>

Useful Options for forge add

Here are some options I use with forge add:

• --shallow: This performs a shallow clone of the repository. It’s faster and uses less disk space, which is great for large repos or when you don’t need the full git history. The downside is you can’t easily switch branches or tags later.
• --no-git: This installs the dependency without adding it as a git submodule. I use this when I’m already in a git repository and don’t want nested git repos.
• --commit: This creates a commit after installing the dependencies. This is handy for keeping your git history clean and making sure the dependency addition is tracked.

Example: Adding the Covenant Project as a Dependency

After initializing my covenant-fuzz project, I added the Covenant repository as a dependency. I wanted to give it an alias covenant so I could import contracts like import "covenant/src/Contract.sol";. I also used --shallow and --commit for a clean setup.

Here’s the command I used:

forge add covenant=code-423n4/2025-10-covenant --shallow --commit

This command fetches the Covenant repository, places it in lib/covenant, and records the change in my git history. Now I can easily reference the Covenant contracts in my fuzzing tests.