leo add - Leo

The leo add command adds dependencies to your Leo project, either from the Aleo network or from local directories.

Syntax

leo add <NAME> [OPTIONS]

Arguments

NAME

string

required

The dependency name. Can be specified with or without .aleo suffix.Examples:

credits.aleo
credits (automatically adds .aleo)

Options

-l, --local

string

Path to local dependency directory. Mutually exclusive with --network.

-n, --network

boolean

Fetch dependency from the network. Mutually exclusive with --local.

-e, --edition

number

Expected edition of the program.

DO NOT USE unless you know what you are doing. Incorrect editions can cause build failures.

--dev

boolean

default:false

Add as a development dependency. Dev dependencies are only used during testing.

Examples

Add Network Dependency

leo add credits.aleo --network

Output:

✅ Added network dependency `credits.aleo`.

Updates program.json:

{
  "dependencies": [
    {
      "name": "credits.aleo",
      "location": "network"
    }
  ]
}

Add Network Dependency (Short Syntax)

leo add credits --network

Automatically appends .aleo:

✅ Added network dependency `credits.aleo`.

Add Local Dependency

leo add my_lib --local ../my_lib

Output:

✅ Added local dependency to program `my_lib.aleo` at path `../my_lib`.

Updates program.json:

{
  "dependencies": [
    {
      "name": "my_lib.aleo",
      "location": "local",
      "path": "../my_lib"
    }
  ]
}

Add with Specific Edition

leo add token --network --edition 0

Updates program.json:

{
  "dependencies": [
    {
      "name": "token.aleo",
      "location": "network",
      "edition": 0
    }
  ]
}

Add Development Dependency

leo add test_utils --local ../test_utils --dev

Updates program.json:

{
  "dev_dependencies": [
    {
      "name": "test_utils.aleo",
      "location": "local",
      "path": "../test_utils"
    }
  ]
}

Development dependencies are only included when building tests with leo test or leo build --build-tests.

Overwrite Existing Dependency

leo add my_lib --local ../my_lib_v2

Output:

⚠️  Program `my_lib.aleo` already exists as a local dependency at `../my_lib`. Overwriting.
✅ Added local dependency to program `my_lib.aleo` at path `../my_lib_v2`.

Dependency Types

Network Dependencies

Fetched from the Aleo network:

leo add credits.aleo --network

Characteristics:

Downloaded during build
Cached for performance
Must be deployed on the network
Automatically updated on rebuild

Local Dependencies

Referenced from local filesystem:

leo add my_lib --local ../my_lib

Characteristics:

Built from source code
Changes reflected immediately
Must exist at specified path
Ideal for development

Dependency Locations

Dependency paths can be:

Relative Paths

leo add my_lib --local ../my_lib
leo add shared --local ../../shared

Absolute Paths

leo add my_lib --local /home/user/projects/my_lib

Program Structure

After adding dependencies, your program.json looks like:

{
  "program": "my_program.aleo",
  "version": "0.1.0",
  "description": "My Aleo program",
  "license": "MIT",
  "leo": "2.0.0",
  "dependencies": [
    {
      "name": "credits.aleo",
      "location": "network"
    },
    {
      "name": "my_lib.aleo",
      "location": "local",
      "path": "../my_lib"
    }
  ],
  "dev_dependencies": [
    {
      "name": "test_utils.aleo",
      "location": "local",
      "path": "../test_utils"
    }
  ]
}

Using Dependencies

After adding dependencies, import them in your Leo code:

import credits.aleo;
import my_lib.aleo;

program my_program.aleo {
    transition main() {
        // Use imported programs
        let result: u64 = my_lib.aleo/calculate(100u64);
        return result;
    }
}

Build Process

When you run leo build:

Dependency Resolution:
- Reads program.json
- Downloads network dependencies
- Locates local dependencies
Dependency Build:
- Builds dependencies in dependency order
- Caches network dependencies
- Compiles local dependencies from source
Main Program Build:
- Compiles main program with dependencies available
- Links to dependency bytecode

Dependency Graph

Leo automatically resolves dependency graphs:

my_program.aleo
├── credits.aleo (network)
└── my_lib.aleo (local)
    └── helper.aleo (network)

Build order: credits → helper → my_lib → my_program

Common Patterns

Standard Library Dependencies

leo add credits.aleo --network

The credits.aleo program is commonly used for:

Token transfers
Fee payments
Balance queries

Multi-Project Workspace

workspace/
├── shared_lib/
│   ├── src/
│   └── program.json
├── project_a/
│   ├── src/
│   └── program.json
└── project_b/
    ├── src/
    └── program.json

cd project_a
leo add shared_lib --local ../shared_lib

cd ../project_b
leo add shared_lib --local ../shared_lib

Test Dependencies

leo add test_helpers --local ../test_helpers --dev

Use in tests:

import test_helpers.aleo;

program my_program.aleo {
    @test
    transition test_main() {
        let result: bool = test_helpers.aleo/assert_eq(1u32, 1u32);
        assert(result);
    }
}

Dependency Caching

Network dependencies are cached:

~/.leo/cache/
├── testnet/
│   └── credits.aleo/
│       └── edition-0/
│           ├── program.aleo
│           └── metadata.json
└── mainnet/
    └── ...

Cache behavior:

Dependencies downloaded once
Reused across projects
Updated on leo build --no-cache

Troubleshooting

Dependency Not Found on Network

Failed to fetch program 'my_program.aleo' from network.

Ensure:

Program is deployed on the network
Program name is correct
Network endpoint is accessible

Local Dependency Not Found

Failed to read dependency at path '../my_lib'.

Check:

Path is correct (relative or absolute)
Directory contains valid Leo project
program.json exists in dependency

Circular Dependencies

Circular dependency detected: A → B → A

Restructure your code:

Extract shared logic to common dependency
Remove circular references
Use dependency injection patterns

Invalid Program Name

Invalid program name: my-program

Program names must:

End with .aleo
Contain only alphanumeric characters and underscores
Start with a letter

Valid: my_program.aleo, token123.aleo Invalid: my-program.aleo, 123token.aleo

Version Conflicts

If dependencies require different Leo versions:

Dependency 'my_lib' requires Leo 1.9.0, but current version is 2.0.0.

Solutions:

Update dependency to match Leo version
Use compatible dependency version
Update Leo CLI

Best Practices

1. Use Specific Editions

For production, pin dependency editions:

leo add token --network --edition 0

2. Local for Development, Network for Production

# Development
leo add my_lib --local ../my_lib

# Production (after deploying my_lib)
leo remove my_lib
leo add my_lib --network

3. Separate Dev Dependencies

leo add test_utils --local ../test_utils --dev
leo add mock_data --local ../mocks --dev

4. Document Dependencies

Update README.md:

## Dependencies

- `credits.aleo` - Standard token operations
- `my_lib.aleo` - Custom business logic

5. Version Control

Commit program.json but not cached dependencies:

# .gitignore
.leo/
build/
outputs/
.env

Get Started

Leo Language

CLI Commands

Development

Advanced

Documentation Index

​Syntax

​Arguments

​Options

​Examples

​Add Network Dependency

​Add Network Dependency (Short Syntax)

​Add Local Dependency

​Add with Specific Edition

​Add Development Dependency

​Overwrite Existing Dependency

​Dependency Types

​Network Dependencies

​Local Dependencies

​Dependency Locations

​Relative Paths

​Absolute Paths

​Program Structure

​Using Dependencies

​Build Process

​Dependency Graph

​Common Patterns

​Standard Library Dependencies

​Multi-Project Workspace

​Test Dependencies

​Dependency Caching

​Troubleshooting

​Dependency Not Found on Network

​Local Dependency Not Found

​Circular Dependencies

​Invalid Program Name

​Version Conflicts

​Best Practices

​1. Use Specific Editions

​2. Local for Development, Network for Production

​3. Separate Dev Dependencies

​4. Document Dependencies

​5. Version Control

​Next Steps

Build docs developers (and LLMs) love

Syntax

Arguments

Options

Examples

Add Network Dependency

Add Network Dependency (Short Syntax)

Add Local Dependency

Add with Specific Edition

Add Development Dependency

Overwrite Existing Dependency

Dependency Types

Network Dependencies

Local Dependencies

Dependency Locations

Relative Paths

Absolute Paths

Program Structure

Using Dependencies

Build Process

Dependency Graph

Common Patterns

Standard Library Dependencies

Multi-Project Workspace

Test Dependencies

Dependency Caching

Troubleshooting

Dependency Not Found on Network

Local Dependency Not Found

Circular Dependencies

Invalid Program Name

Version Conflicts

Best Practices

1. Use Specific Editions

2. Local for Development, Network for Production

3. Separate Dev Dependencies

4. Document Dependencies

5. Version Control

Next Steps