Skip to content


Woke comes with default compilation settings that should work for many projects. However, in some cases, it may be necessary to customize the compilation settings.

To run the compiler, use:

woke compile

The --help flag can be used to display additional options.

Include paths#

Include paths define locations where to search for Solidity files imported using direct (non-relative) import strings. An example of a direct import string is:

import "openzeppelin/contracts/token/ERC20/ERC20.sol";

The default settings for include paths are:

include_paths = ["node_modules"]


Include paths should only be used if path segments (directories in the import string) reflect directories in the file system.

For example, if the import string is import "openzeppelin/contracts/token/ERC20/ERC20.sol";, but the file is located at node_modules/openzeppelin/src/contracts/token/ERC20/ERC20.sol, then include paths cannot be used because of the src directory in the path.


Remappings allow performing a substitution in import strings. More information about remappings can be found in the Solidity documentation.


It is highly recommended to use include paths instead of remappings whenever possible.

Foundry projects#

Include paths typically cannot be used in Foundry projects. The forge remappings command can generate remappings that can be copied into the woke.toml file:

$ forge remappings

remappings = [

Ignore paths#

Ignore paths define locations where to ignore Solidity files when searching for contracts to compile. Solidity files in these locations will not be compiled unless imported from another non-ignored file.

The default settings for ignore paths are:

ignore_paths = ["node_modules", ".woke-build", "venv", "lib"]

Via IR#

The compiler can can generate bytecode by converting the sources to Yul first (Solidity -> Yul -> EVM bytecode) instead of the traditional Solidity -> EVM bytecode approach. See the Solidity documentation for more information.

By default, the via_IR config option is left unset, which leaves the decision to the compiler. It can be enabled by setting the option to true:

via_IR = true

Stack too deep errors

One way to avoid Stack too deep errors is to enable via_IR and the optimizer.


The compiler can optimize the bytecode generated by the compiler. Woke allows enabling/disabling the optimizer and setting the runs parameter. runs specifies roughly how often each opcode of the deployed code will be executed across the lifetime of the contract. This allows managing a tradeoff between code size and code execution cost.

By default, Woke leaves the enabled option unset, which leaves the decision to the compiler. It can be enabled by setting the option to true:

enabled = true
runs = 200