Set up a Solidity smart contract project with OpenZeppelin Contracts. Use when users need to: (1) create a new Hardhat or Foundry project, (2) install OpenZeppelin Contracts dependencies for Solidity, (3) configure remappings for Foundry, or (4) understand Solidity import conventions for OpenZeppelin.
For existing projects, detect the framework by looking for hardhat.config.* (Hardhat) or foundry.toml (Foundry). For new projects, ask the user which framework they prefer.
npx hardhat init # Hardhat v2
npx hardhat --init # Hardhat v3
npm install @openzeppelin/contracts
npm install @openzeppelin/contracts-upgradeable
curl -L https://foundry.paradigm.xyz | bash
foundryup
forge init my-project
cd my-project
forge install OpenZeppelin/openzeppelin-contracts@v<VERSION>
forge install OpenZeppelin/openzeppelin-contracts-upgradeable@v<VERSION>
Look up the current version from https://github.com/OpenZeppelin/openzeppelin-contracts/releases. Pin to a release tag — without one,
forge installpulls the default branch, which may be unstable.
remappings.txt (if not using upgradeable contracts)@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/
remappings.txt (if using upgradeable contracts)@openzeppelin/contracts/=lib/openzeppelin-contracts-upgradeable/lib/openzeppelin-contracts/contracts/
@openzeppelin/contracts-upgradeable/=lib/openzeppelin-contracts-upgradeable/contracts/
Note The above remappings mean that both
@openzeppelin/contracts/(including proxy contracts) and@openzeppelin/contracts-upgradeable/come from theopenzeppelin-contracts-upgradeablesubmodule and its subdirectories, which includes its own transitive copy ofopenzeppelin-contractsof the same release version number. This format is needed for Etherscan verification to work. Particularly, any copies ofopenzeppelin-contractsthat are installed separately are NOT used.
@openzeppelin/contracts/token/ERC20/ERC20.sol@openzeppelin/contracts-upgradeable/token/ERC20/ERC20Upgradeable.sol