Installation

This page explains how to install FlatCAM Evo on Windows, Linux and macOS. It also explains how to run FlatCAM Evo from the source code, and how to start it for the first time.

Choose your installation

Your system	Recommended way	Section
Windows	Windows release package from the Releases page	Windows
Windows (developer or latest code)	Source code with conda / mamba, or pip and a virtual environment	From source
Debian / Ubuntu	setup_ubuntu.sh script	Linux
macOS	Source code with Homebrew Python and pip	macOS

Read Glossary if a term is not clear.

Requirements

• Python 3.10 or newer. Use a 64-bit Python. The OR-Tools path optimization works only on 64-bit Python.
• A working OpenGL context and graphics driver. The 2D canvas uses VisPy and needs OpenGL.
• The Python packages listed in requirements.txt. The main packages are PyQt6, Shapely 2, NumPy, Rtree, VisPy, ezdxf, svglib, reportlab and lxml.

Check your Python version:

python --version

If the version is lower than 3.10, install a newer Python first.

Windows

Option 1: Windows release package

1. Open the Releases page of the project: https://github.com/MariusAdrian88/FlatCAM_Evo/releases.
2. Download the newest Windows package.
3. Follow the instructions of the release for the installation. The package contains FlatCAM.exe, which starts the program.
4. Start FlatCAM.exe.

The package also contains FlatCAM-cli.exe (command line and headless mode) and FlatCAMUpdater.exe (the updater).

Screenshot placeholder: images/Installation-1.png — the Releases page with the Windows package highlighted.

Note: FlatCAM Evo 1.0 cannot update itself. Install version 1.01 or newer with the installer one time. See Updates.

Option 2: From source on Windows

Install Python from python.org. Select Add python.exe to PATH during the setup.

Open PowerShell in the project folder, then run:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -r requirements-optional.txt

The last command is optional. FlatCAM Evo runs without it.

If pip cannot install gdal:

1. Download a GDAL wheel for your Python version from cgohlke/geospatial-wheels.
2. Install the wheel with python -m pip install <wheel file>.
3. Run the requirements.txt command again.

Or use conda / mamba (see From source).

Linux

Debian and Ubuntu: the setup script

The script setup_ubuntu.sh in the project folder installs everything. It works on Debian, Ubuntu and other apt-based distributions.

cd FlatCAM_Evo
./setup_ubuntu.sh
.venv/bin/python flatcam.py

What the script does:

1. It installs the system packages with apt. It asks for your sudo password.
2. It creates the virtual environment .venv in the project folder.
3. It installs the GDAL Python package. The version matches the GDAL system library.
4. It installs requirements.txt.
5. It tries to install requirements-optional.txt. If this step fails, the script continues.

To use another Python 3.10 or newer, set the PYTHON variable:

PYTHON=python3.12 ./setup_ubuntu.sh

Other Linux distributions

Install the system libraries with your package manager. On Debian and Ubuntu, the packages are:

sudo apt install python3-venv python3-dev build-essential \
     libgeos-dev libspatialindex-dev libfreetype6-dev gdal-bin libgdal-dev \
     libgl1 libegl1 libxkbcommon-x11-0 libxcb-cursor0

Then create the virtual environment and install the packages:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install "gdal==$(gdal-config --version)"
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip install -r requirements-optional.txt

Newer distributions refuse a system-wide pip install. Always use the virtual environment.

Application menu entry (optional)

The README describes a make install target. It adds FlatCAM Evo to the applications menu of your user. Use sudo make install to install it for all users. Use make remove to remove it.

macOS

Install Homebrew. Then install the system libraries and Python:

brew install python geos spatialindex freetype gdal

Create the virtual environment and install the packages in the project folder:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -r requirements-optional.txt

If gdal fails to install, check that the Homebrew gdal package is installed. Then run the pip command again.

From source (all systems)

1. Get the source code

git clone https://github.com/MariusAdrian88/FlatCAM_Evo.git
cd FlatCAM_Evo

The branch main is the stable branch. For the newest development code, run git checkout 1.0.

2a. conda or mamba (recommended for all systems)

Conda installs the packages that need system libraries (GDAL, GEOS, libspatialindex, FreeType).

1. Install Miniforge. It includes mamba.

2. Create the environment from environment.yml:

   mamba env create -f environment.yml

3. Activate the environment:

   mamba activate flatcam

4. Start the program with python flatcam.py.

The file environment.yml pins numpy==1.26.4. It installs ortools, pyqt6 and vtracer with pip inside the environment.

2b. pip and a virtual environment

Use this way when you do not use conda. Follow the section for your system above. The packages are the same.

File	Content	Needed
requirements.txt	Main Python packages	Yes
requirements-optional.txt	pyclipr, a faster Gerber fusion	No
environment.yml	Conda environment with the same packages	Only for conda

Optional packages and the features they add:

Package	Feature	Without the package
ortools	MetaHeuristic and Basic path optimization of drill and mill paths	The path optimization is not available.
rasterio with GDAL	Image import plugin	The Image import plugin is not loaded.
vtracer	Tracing mode of the Image import plugin	The tracing mode is not available.
pikepdf	Alternative PDF parser	The built-in PDF parser is used.
pyclipr	Faster fusion of Gerber geometry when a file opens	FlatCAM Evo uses the slower method.

3. Start FlatCAM Evo for the first time

From the project folder, with the environment active:

python flatcam.py

Without an activated environment, use the Python of the virtual environment directly: .venv\Scripts\python.exe flatcam.py on Windows, or .venv/bin/python flatcam.py on Linux and macOS.

You can open files on the command line:

python flatcam.py board.FlatPrj
python flatcam.py top.gbr drills.drl

What happens on the first start:

1. FlatCAM Evo creates its data folder. See FAQ and Troubleshooting.
2. The main window opens with the Project and Properties tabs.
3. The log file log.txt is written in the data folder.

Screenshot placeholder: images/Installation-2.png — the main window after the first start, with the empty Project tab.

If the program does not start

• Check the Python version. FlatCAM Evo needs Python 3.10 or newer.
• Check that the packages are installed in the active environment.
• If the message OpenGL initialization failed appears, see FAQ and Troubleshooting.

Command line options

Option	Use
FILE	Open a project (.FlatPrj), a script (.FlatScript, .tcl), or a Gerber, Excellon or G-code file.
--shellfile=SCRIPT	Run a Tcl script after the start.
--shellvar=VALUE1,VALUE2	Define the Tcl variables shellvar_0, shellvar_1, and so on.
--command=COMMANDS	Run Tcl commands separated by semicolons. Use quotes.
--headless	Run without a window. See Command Line and Headless.

Next steps

• Read Getting Started for the basic workflow.
• Follow Tutorial Single-Sided PCB for a first board.
• Read User Interface to learn the main window.

See also

• Getting Started
• Updates
• Command Line and Headless
• FAQ and Troubleshooting
• Preferences Overview