Installing CadQuery

CadQuery may be installed with either conda or pip. The conda installation method is the better tested and more mature option.

Install via conda

Begin by installing the conda package manager. If conda is already installed skip to conda.

Install the Conda Package Manager

In principle, any Conda distribution will work, but it is probably best to install Miniforge to a local directory and to avoid running conda init. After performing a local directory installation, Miniforge can be activated via the [scripts,bin]/activate scripts. This will help avoid polluting and breaking the local Python installation.

In Linux/MacOS, the local directory installation method looks something like this:

# Install the script to ~/miniforge
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O miniforge.sh
bash miniforge.sh -b -p $HOME/miniforge

# To activate and use Miniconda
source $HOME/miniforge/bin/activate

On Windows, download the installer and double click it on the file browser or install non-interactively as follows:

:: Install
curl -L -o miniforge.exe https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe
start /wait "" miniforge.exe /InstallationType=JustMe /RegisterPython=0 /NoRegistry=1 /NoScripts=1 /S /D=%USERPROFILE%\Miniforge3

:: Activate
cmd /K ""%USERPROFILE%/Miniforge3/Scripts/activate.bat" "%USERPROFILE%/Miniforge3""

It might be worthwhile to consider using /NoScripts=0 to have an activation shortcut added to the start menu.

After conda installation, create and activate a new conda environment to prepare for cadquery installation.

Note that miniforge automatically sets conda-forge as the default channel. -c conda-forge can be omitted from the install command when using a miniforge installation.

conda

Install the latest released version of cadquery [1]:

conda create -n cqrel
conda activate cqrel
conda install -c conda-forge cadquery occt=7.7.0

or install a given version of cadquery [1]:

conda create -n cq22
conda activate cq22
conda install -c conda-forge cadquery=2.2.0 occt=7.7.0

or install the latest dev version:

conda create -n cqdev
conda activate cqdev
conda install -c cadquery -c conda-forge cadquery=master

Install via pip

CadQuery has a complex set of dependencies including OCP, which is our set of bindings to the OpenCASCADE CAD kernel. OCP is distributed as binary wheels for Linux, MacOS and Windows. However, there are some limitations. Only Python 3.8 through 3.10 are currently supported, and some older Linux distributions such as Ubuntu 18.04 are not supported. If the pip installation method does not work for your system, you can try the conda installation method.

It is highly recommended that a virtual environment is used when installing CadQuery, although it is not strictly required. Installing CadQuery via pip requires an up-to-date version of pip, which can be obtained with the following command line (or a slight variation thereof).:

python3 -m pip install --upgrade pip

Once a current version of pip is installed, CadQuery can be installed using the following command line.:

pip install cadquery

It is also possible to install the very latest changes directly from CadQuery’s GitHub repository, with the understanding that sometimes breaking changes can occur. To install from the git repository, run the following command line.:

pip install git+https://github.com/CadQuery/cadquery.git

You should now have a working CadQuery installation, but developers or users who want to use CadQuery with IPython/Jupyter or to set up a developer environment can read the rest of this section.

If you are installing CadQuery to use with IPython/Jupyter, you may want to run the following command line to install the extra dependencies.:

pip install cadquery[ipython]

If you want to create a developer setup to contribute to CadQuery, the following command line will install all the development dependencies that are needed.:

pip install cadquery[dev]

Adding a Nicer GUI via CQ-editor

If you prefer to have a GUI available, your best option is to use CQ-editor.

Example cq-editor installation with conda (this installs both cadquery and cq-editor):

conda create -n cqdev
conda activate cqdev
conda install -c cadquery -c conda-forge cq-editor=master

Example cq-editor installation with pip:

pip install PyQt5 spyder pyqtgraph logbook
pip install git+https://github.com/CadQuery/CQ-editor.git

Jupyter

Viewing models in Jupyter is another good option for a GUI. Models are rendered in the browser.

The cadquery library works out-of-the-box with Jupyter. First install cadquery, then install JupyterLab in the same conda or Python venv.:

conda

conda install -c conda-forge jupyterlab

pip

pip install jupyterlab

Start JupyterLab:

jupyter lab

JupyterLab will open automatically in your browser. Create a Notebook to interactively edit/view CadQuery models.

Call display to show the model.:

display(<Workplane, Shape, or Assembly object>)

Test Your Installation

If all has gone well, you can open a command line/prompt, and type:

$ python
$ import cadquery
$ cadquery.Workplane('XY').box(1,2,3).toSvg()

You should see raw SVG output displayed on the command line if the CadQuery installation was successful.

Note

[1] (1,2)

Installation of the latest release (version 2.2.0) with conda requires you to specify the version of the OCCT dependency. Typically this is not required as the dependencies are managed automatically.