Guide · Open source
How to use OpenZeppelin Contracts: install and build with it
Updated · written with AI from the project's own documentation and checked against our catalogue data
OpenZeppelin Contracts is a library of pre-written Solidity code for building smart contracts on Ethereum-compatible blockchains. It provides implementations of standards such as ERC20 and ERC721, plus role-based permissions and reusable utilities. This guide shows how to install it with npm or Foundry, import a contract from it, and avoid the common mistakes around versions and auditing.
OpenZeppelin ContractsOpenZeppelin/openzeppelin-contracts · ★ 27.3k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you know Solidity and have Node.js for npm, or Foundry if you prefer git.
- 2Install the library. Run npm install @openzeppelin/contracts for the audited release, or forge install OpenZeppelin/openzeppelin-contracts with Foundry.
- 3Add a remapping. If you use Foundry, add the @openzeppelin/contracts remapping in remappings.txt.
- 4Import a contract. Import the file you need, such as the ERC721 token, using its path inside the package.
- 5Inherit and configure. Create your contract, inherit from the imported base and pass the constructor arguments.
- 6Compile and review. Compile your project and review the code before deployment, following the docs for project setup.
What you need before you install OpenZeppelin Contracts
The library is code for developers. The README expects you to know Solidity and to have a smart contract project set up. For the npm route it names Node.js as a prerequisite, but it does not state a required Node.js version, so check the current Hardhat or npm guidance for your setup.
Foundry is optional and only needed if you install the library with git through the forge command.
- Solidity knowledge
- Node.js for the npm and Hardhat install
- Foundry, optional, for the git install
Install the audited release with npm or Hardhat
Run the npm command below in your project. By default it installs the latest audited release, which uses the latest tag.
To install the unaudited dev release instead, add @dev. The README says dev is finalized and tested and can be used in production, but it has not yet been audited.
- latest: stable, audited releases, the default for npm install
- dev: final but not audited, covered by the bug bounty
- next: release candidates for testing, not final
$ npm install @openzeppelin/contractsInstall with Foundry using git
If you use Foundry, install the library with forge. The README warns that the master branch is a development branch and should be avoided in favour of tagged releases.
After installing, add a remapping in remappings.txt so that imports resolve to the installed folder. Note that forge update pulls from master, so pin to a tagged release if you rely on audited code.
- Do not use the master branch for production code
- Add the remapping in remappings.txt
- forge update uses master, according to the README
$ forge install OpenZeppelin/openzeppelin-contracts
@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/Import a contract and write your first token
Once installed, import the contract you need and inherit from it. The example below builds a simple ERC721 collectible. The constructor passes the token name and symbol to the ERC721 base contract.
If you are new to smart contract development, the OpenZeppelin documentation covers creating a project and compiling your contracts. The library also includes a Contracts Wizard, an interactive generator, if you want a starting point.
- Set the pragma to match the library version you installed
- Import only the files you need by path
- Pass constructor arguments to the base contract
pragma solidity ^0.8.20;
import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol";
contract MyCollectible is ERC721 {
constructor() ERC721("MyCollectible", "MCO") {
}
}Use the library as-is, without copying code
The README says you should always use the installed code as-is, and should not copy-paste it from online sources or modify it yourself. This keeps you on the reviewed code path.
The library is designed so that only the contracts and functions you use are deployed, so the README says you need not worry about unnecessary gas costs from importing it.
- Do not edit files inside the installed package
- Do not copy-paste code from unofficial sources
- Extend contracts through inheritance instead
Know what the library does not replace
The README says that using OpenZeppelin Contracts is not a substitute for a security audit. Smart contracts carry a high level of technical risk, and you remain responsible for how you use the code.
Past audits are kept in the audits folder of the repository, and the security policy is in SECURITY.md.
- Get your own security audit before handling real value
- Read SECURITY.md for how to report vulnerabilities
- Past audits are in the audits/ folder
What people use it for
- Launching an NFT collection built on the ERC721 standard
- Creating a fungible token using the ERC20 implementation
- Adding role-based permissions to a contract with the access-control components
- Using reusable utilities such as non-overflowing math and signature verification
Frequently asked questions
Is OpenZeppelin Contracts free to use?
Yes, the library is released under the MIT License, as stated in the README and LICENSE file. The license disclaims warranties and limits liability, so you are responsible for how you use the code.
How do I install OpenZeppelin Contracts?
Use npm install @openzeppelin/contracts for the latest audited release, or forge install OpenZeppelin/openzeppelin-contracts with Foundry. The Foundry route also needs a remapping in remappings.txt.
What is the difference between the latest and dev tags?
The latest tag holds audited releases and is the npm default. The dev tag holds finalized versions that have not yet been audited, and you install it with npm install @openzeppelin/contracts@dev.
Is OpenZeppelin Contracts audited?
The audited releases are the latest npm tag, and past audits are kept in the audits folder. The README also says that using the library is not a substitute for your own security audit.
Can I edit the OpenZeppelin code in my project?
The README says to use the installed code as-is and not modify or copy-paste it. Extend the contracts by inheriting from them instead.
How does OpenZeppelin Contracts compare to Solmate, Solady or Hardhat?
Solmate and Solady are comparable Solidity libraries, and Hardhat is a development environment rather than a contract library. This page only covers OpenZeppelin, so check each project's documentation for a direct comparison.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
OpenZeppelin Contracts suits Solidity developers who need standard tokens like ERC20 and ERC721, or permission systems, and want reviewed code instead of writing it from scratch. It is not a finished app and not a replacement for a security audit, so non-developers and teams that plan to rewrite the code should look elsewhere.
Install options & downloads