CadQuery is an intuitive, easy-to-use Python module for building parametric 3D CAD models. Using CadQuery, you can write short, simple scripts that produce high quality CAD models. It is easy to make many different objects using a single script that can be customized.
CadQuery is often compared to OpenSCAD. Like OpenSCAD, CadQuery is an open-source, script based, parametric model generator. However, CadQuery stands out in many ways and has several key advantages:
The original version of CadQuery was built on the FreeCAD API. This was great because it allowed for fast development and easy cross-platform capability. However, we eventually started reaching the limits of the API for some advanced operations and selectors. This 2.0 version of CadQuery is based directly on a Python wrapper of the OCCT kernel. This gives us a great deal more control and flexibility, at the expense of some simplicity and having to handle the cross-platform aspects of deployment ourselves. We believe this is a worthwhile trade-off to allow CadQuery to continue to grow and expand in the future.
To quickly play around with CadQuery and see it's capabilities, see the CQ-editor GUI manual.
If you want to use CadQuery for your own project, keep reading:
It is currently possible to use CadQuery for your own projects in 3 different ways:
The easiest way to install CadQuery and its dependencies is using conda, which is included as part of an Anaconda/Miniconda installation. See the next section for an alternative to a full install of Anaconda that may be preferable to some users. The steps to install cadquery are as follows:
# Set up a new environment conda create -n cadquery # Activate the new environment conda activate cadquery # CadQuery development is moving quickly, so it is best to install the latest version from GitHub master conda install -c conda-forge -c cadquery cadquery=master
For those who are interested, the OCP repository contains the current OCCT wrapper used by CQ.
For those unfamiliar (or uncomfortable) with Anaconda, it is probably best to install Miniconda to a local directory and to avoid running
conda init. After performing a local directory installation, Miniconda can be activated via the [scripts,bin]/activate scripts. This will help avoid polluting and breaking the local Python installation. In Linux, the local directory installation method looks something like this:
# Install the script to ~/miniconda wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh bash miniconda.sh -b -p $HOME/miniconda # To activate and use Miniconda source $HOME/miniconda/bin/activate
CQ-editor is an IDE that allows users to edit CadQuery model scripts in a GUI environment. It includes features such as:
The installation instructions for CQ-editor can be found here.
CadQuery supports Jupyter notebook out of the box using the jupyter-cadquery extension created by @bernhard-42:
A list of Docker images can be found here, and includes images for the following projects.
CadQuery was built to be used as a Python library without any GUI. This makes it great for use cases such as integration into servers, or creating scientific and engineering scripts. Use Anaconda/Miniconda to install CadQuery, and then add
import cadquery to the top of your Python scripts. If the stable version of CadQuery is desired, the following command will install it. However, be aware that the stable version can fall significantly behind the current state of CadQuery, so in many cases the
master installation method at the beginning of the Getting Started section is preferable.
conda install -c conda-forge -c cadquery cadquery=2
You can find the full CadQuery documentation at cadquery.readthedocs.io.
We also have a Google Group to make it easy to get help from other CadQuery users. We want you to feel welcome and encourage you to join the group and introduce yourself. We would also love to hear what you are doing with CadQuery.
There is a Discord channel as well. A big thanks goes to the Elmer team for hosting us.
Here are just a few examples of how CadQuery is being used.
FxBricks uses CadQuery in the product development pipeline for their Lego train system. FxBricks has also given back to the community by creating documentation for their CAD pipeline. They have also assembled cq-kit, a library containing utility classes and functions to extend the capabilities of CadQuery. Thanks to @michaelgale and @fx-bricks for this example.
Hexidor is an expanded take on the Quoridor board game, and the development process has been chronicled here. CadQuery was used to generate the game board. Thanks to Bruce for this example.
CadQuery is licensed under the terms of the Apache Public License, version 2.0.
Contributions from the community are welcome and appreciated.
You do not need to be a software developer to have a big impact on this project. Contributions can take many forms including, but not limited to, the following:
It is asked that all contributions to this project be made in a respectful and considerate way. Please use the Python Community Code of Conduct's guidelines as a reference.
If you are going to contribute code, make sure to follow this steps:
conda env create -n cq-dev -f environment.yml
conda activate cq-dev
conda install -c cadquery -c conda-forge cq-editor=masterInstalling cq-editor adds another instance of cadquery which overrides the clone just added. Fix this by reinstalling cadquery using pip:
pip install -e .
pytestfrom the root of your cadquery clone, there should be no failures and the output will look similar to this:
blackto autoformat your code and make sure your code style complies with CadQuery's
When filing a bug report issue, please be sure to answer these questions:
If you find yourself wishing for a feature that does not exist, you are probably not alone. There are bound to be others out there with similar needs. Open an issue which describes the feature you would like to see, why you need it, and how it should work.