// Before you start
What you need
- A computer running macOS, Linux, or Windows with WSL2
- Node.js 20 or later installed (nodejs.org)
- pnpm package manager installed (pnpm.io)
- MongoDB 6 or later installed and running locally
- Git installed (git-scm.com)
- At least 8 GB of free disk space and 4 GB RAM
You need your own copy of the code on GitHub before you can work with it. Forking creates a personal copy on GitHub; cloning downloads it to your computer. Replace YOUR_USERNAME with your actual GitHub username.
$ git clone https://github.com/YOUR_USERNAME/freeCodeCamp.git
$ cd freeCodeCamp
What you should see
A folder called freeCodeCamp appears in your current directory. Your terminal prompt moves into that folder.
This might happen
Clone takes a very long time or stalls
The repo is large. Use a wired connection if possible. If it times out, re-run the same git clone command — it will resume.
The project ships a sample config file with all the settings you need for local development. You copy it to create your real config file. You do not need to edit anything inside it to get the site running for the first time.
What you should see
A new file called .env appears in the freeCodeCamp folder. No output is printed if the command succeeds.
This might happen
On Windows (outside WSL2) the cp command is not recognised
Run this instead: copy sample.env .env
This downloads every library the project needs. pnpm is faster than npm and is what the project officially supports. Expect a lot of text scrolling past — that is normal.
What you should see
The last lines will say something like 'Done in Xs'. A node_modules folder is created.
This might happen
Errors about missing native build tools (node-gyp, python)
On Ubuntu/Debian run: sudo apt install build-essential python3. On macOS run: xcode-select --install. Then re-run pnpm install.
The platform needs a database pre-filled with curriculum data and a test user account. This command creates all of that automatically. Make sure MongoDB is already running before you run this.
What you should see
You should see messages confirming that collections were created and documents were inserted. The command exits cleanly with no red error text.
This might happen
Connection refused or MongoDB not found
Start MongoDB first. On Linux/macOS: sudo systemctl start mongod or brew services start mongodb-community. Then re-run pnpm run seed.
This command compiles the code and starts both the API server and the front-end. It takes a minute or two before the site is ready. Watch the terminal for a URL to open.
What you should see
You will eventually see lines like 'Client is ready at http://localhost:8000' and 'API is ready at http://localhost:3000'. Open http://localhost:8000 in your browser.
This might happen
Port 8000 or 3000 is already in use
Find and stop whatever is using those ports. On macOS/Linux: lsof -i :8000 then kill the listed PID. On Windows: netstat -ano | findstr :8000 then taskkill /PID <number> /F.
// Status
cooked. baked. worked.
A fully working local copy of freeCodeCamp running in your browser at http://localhost:8000, connected to a local database, ready for you to test curriculum changes or contribute fixes.
// the honest bit
The honest part
This guide is for contributors who want to run the platform locally to test edits — not for learners. If you just want to learn, go to freecodecamp.org and use it there for free with no setup. The local setup is a full developer environment with real complexity. Non-developers will likely hit friction with MongoDB setup, WSL2 on Windows, or native build tools. The freeCodeCamp contributing docs at contribute.freecodecamp.org are detailed and worth reading if anything breaks.
