# CadQuery: parametric CAD as a Python script, not a GUI session > CadQuery builds 3D models from Python code on top of the OpenCASCADE kernel. It suits engineers who want models under version control and generated on a server, and it asks you to accept a script-first workflow with a conda-first installation. **CadQuery/cadquery** — A python parametric CAD scripting framework based on OCCT - Repository: https://github.com/CadQuery/cadquery - Website: https://cadquery.org - Stars: 5,874 · Forks: 549 - Language: Python - License: NOASSERTION - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/cadquery-cadquery ## The problem CadQuery targets: models that change and models that must be generated A GUI CAD session produces a file. Change one dimension and you reopen the file, find the feature, edit it, and re-export. CadQuery produces a program instead. The README states the module is for building parametric 3D models and that a single script can be customized to make many different objects. That is the core claim: the model is the source, and the artifact is an output. The second half of the claim matters more for infrastructure work. CadQuery was built as a Python library without any GUI, which the README says makes it suitable for integration into servers or for scientific and engineering scripts. A pipeline that needs a bracket sized from a database row, or a batch of enclosures exported to STEP overnight, is the target. The output formats listed are STEP and DXF as loss-less CAD formats, plus STL, VRML, AMF and 3MF for mesh consumers. Who this is for, concretely: developers and engineers already comfortable in Python, people who want diffs on geometry instead of binary blobs, and teams that need the same model family generated at many parameter values. It is not aimed at someone who wants to push and pull faces with a mouse. ## How CadQuery builds geometry: a fluent API over the OCCT kernel CadQuery is not a CAD kernel. The setup.py dependency list pins cadquery-ocp==8.0.1.*, and the README points to the OCP repository as the current OCCT wrapper used by CadQuery. OpenCASCADE does the B-rep work: booleans, fillets, lofts, sweeps, STEP translation. CadQuery provides the Python surface over it. That surface is a chain of operations on a workplane. A script selects a plane, draws a closed wire, extrudes or revolves it, then selects faces or edges on the result and applies further operations. Selection is by string filters rather than by indices, which is why a script stays readable when the underlying topology changes after an edit. The README lists fillets, curvilinear extrudes, parametric curves and lofts among the advanced capabilities, and the examples directory shows the same vocabulary in file form: Ex002 bores a center hole, Ex012 creates workplanes on faces, Ex017 shells to thin features, Ex018 makes lofts, Ex023 sweeps. Assemblies are nested: the README describes building nested assemblies out of individual parts and other assemblies. Export goes through the same object graph, so a part script and an assembly script share their geometry code. The trade-off in this design is that every operation is a kernel call, and kernel calls fail on degenerate input. A fillet radius larger than the adjacent face, a sweep with a self-intersecting path, a boolean between solids that touch exactly at a face: these raise errors from OCCT rather than being smoothed over by an interactive modeler. You get the error in a traceback, which is better than a silent wrong shape, but it is work you have to do. ## Installing CadQuery and running a first filleted box The README is explicit that conda-based installation, or the CQ-editor installer, is the better supported option. The conda route creates an environment and installs from conda-forge, with mamba recommended over conda for speed and memory use. ```bash conda create -n cadquery conda activate cadquery mamba install -c conda-forge cadquery ``` A development build is available from the same channel set with cadquery=master appended. The pip route is documented as the second choice because of the OCP wheel constraints. ```bash python3 -m pip install --upgrade pip pip install cadquery ``` The README states that OCP ships binary wheels for Linux, macOS and Windows, that only Python 3.9 through 3.12 are currently supported, and that some older Linux distributions such as Ubuntu 18.04 are not. If pip fails on your system, the documented fallback is conda. Installing straight from the repository is also documented and carries the warning that breaking changes can occur. ```bash pip install git+https://github.com/CadQuery/cadquery.git ``` For a first real use, the README's own visualization example builds a unit box, selects the edges parallel to the Z axis with the filter "|Z", and fillets them. With the trame and vtk based viewer this opens a window showing the rounded block. ```python from cadquery.func import box, fillet from cadquery.vis import show b = box(1,1,1) show(fillet(b, b.edges("|Z"), 0.1)) ``` The README notes a second variant, importing show from cadquery.fig, for a non-blocking and persistent view. If you have no display, the container path is documented: an apptainer image at ghcr.io/cadquery/cadquery-apptainer:master, or a podman or docker invocation of ghcr.io/cadquery/cadquery-docker:master with /dev/dri passed through and the display variable forwarded. Jupyter is supported out of the box, where calling display() renders the model in the notebook. ## Where CadQuery stops being the right tool The installation constraints are the first hard boundary. Python 3.9 through 3.12 only, for the pip path. If your organization standardizes on a newer interpreter, or on a Linux distribution the OCP wheels do not cover, you are on the conda path or you are not running CadQuery at all. The README does not document a source build of OCP as a workaround. The second boundary is interactive work. CadQuery has internal visualization, and CQ-editor adds a graphical debugger and a stack inspector, but neither is a sketcher. There is no constraint solver to drag a line until it is tangent to an arc. If your design process is exploratory, where the shape is discovered by manipulating it, a script is a poor medium, and you will spend more time encoding intent than forming it. The third is assemblies. The README says nested assemblies of parts and sub-assemblies are supported. It does not describe mates, degrees of freedom, or motion studies. Treat CadQuery assemblies as a product structure for export and bill-of-materials style organization, not as a kinematic model. If you need to check that a linkage sweeps without collision, that check lives elsewhere. Finally, error surfaces are kernel-shaped. OCP is a binding layer over OCCT, and OCCT reports failures as exceptions with kernel terminology. A script that worked at one parameter value can fail at another because a fillet no longer fits. This is inherent to parametric modeling, but CadQuery gives you no graphical preview to see it coming; you find out when the batch run stops. ## CadQuery against OpenSCAD and build123d OpenSCAD is the obvious comparison for anyone arriving from script-based CAD. It has its own language, its own evaluator, and it renders meshes. CadQuery is Python and produces B-rep solids through OCCT, which is why the README can list STEP and DXF as loss-less outputs alongside the mesh formats. The practical difference: in OpenSCAD you are composing primitives and CSG operations in a domain-specific language, while in CadQuery you are calling a Python API and can use the rest of the Python ecosystem around it, including the numpy and scipy stack present in the dependency list. The cost is that CadQuery needs a heavier install, OCP plus the trame visualization stack, where OpenSCAD is a single binary. build123d is the closer comparison, since it is built on the same OCCT bindings. The difference is API philosophy: CadQuery's builder pattern and string-based selectors are the established surface, while build123d takes a different approach to how objects and contexts are expressed. Both give you Python and OCCT, so the choice is about which API reads better to your team and which one your existing scripts already use. There is no data-format lock-in either way, since STEP is the interchange. If your requirement is a full application with a sketcher, a constraint solver and a mate system, FreeCAD is the alternative, and it is a different category of tool. CadQuery is a library you call; FreeCAD is an application you operate, with a Python console inside it. Choosing CadQuery means choosing to write code as the primary modeling activity. ## Maintenance, licensing and the cost of upgrading The repository is not archived and the last push was on 2026-09-13. Releases are regular: v2.6.1 on 2025-10-28, v2.7.0 on 2026-02-13, v2.8.0 on 2026-06-20, with setup.py carrying version 2.9.0dev on master. That cadence tells you the project is moving, and it also tells you the upgrade cost. CadQuery pins its kernel. The dependency line is cadquery-ocp==8.0.1.*, an exact-match pin on the OCCT bindings. When OCP moves, CadQuery moves with it, and your environment has to move too. The README warns that installing from the git repository can bring breaking changes. In practice this means you should pin the cadquery version in your own environment file, keep the model scripts in the same repository as that pin, and re-run your export batch after any upgrade rather than assuming a patch release is inert. The examples directory and the test suite are the reference for what the API is supposed to do at a given version. On licensing, the repository metadata reports NOASSERTION for the licence field, but setup.py carries the Apache License, Version 2.0 header and declares license="Apache Public License 2.0", and the LICENSE file sits at the top level. The Apache 2.0 text includes an explicit patent grant, which matters for a CAD library you might embed in a product. Note that the OCP bindings and the OCCT kernel underneath are separate projects with their own terms; check those before shipping a commercial product, and treat this as a pointer to the files rather than as legal advice. ## Conclusion Adopt CadQuery if your models change by parameters, need to live in Git, or must be produced on a machine with no display. Skip it if you need interactive sketching or a mature assembly mate solver. Verify first that your Python is 3.9 through 3.12 for the pip route, and run the box and fillet example before committing a project to it. ## FAQ ### What can you do with CadQuery? It builds parametric 3D CAD models from Python scripts, with fillets, curvilinear extrudes, parametric curves, lofts and nested assemblies listed among its capabilities. It exports STEP and DXF as loss-less CAD formats plus STL, VRML, AMF and 3MF, and it runs without a GUI, which suits server-side and scientific scripting. ### How do I install CadQuery? The README says conda-based installation is the better supported option: create an environment, activate it, and run mamba install -c conda-forge cadquery. The pip route is pip install cadquery after upgrading pip, with the caveat that OCP wheels only cover Python 3.9 through 3.12 and some older Linux distributions such as Ubuntu 18.04 are not supported. ### Is CadQuery free and open source? The source is public on GitHub under the CadQuery organization, and setup.py declares the Apache Public License 2.0 with the licence header in the file and a LICENSE file at the repository root. The repository metadata reports the licence field as NOASSERTION, so read the LICENSE file itself for the terms. ### How is CadQuery different from FreeCAD? CadQuery is a Python library built to be used without any GUI, aimed at scripts, servers and automation. FreeCAD is an application you operate, with a Python console inside it. If your modeling activity is writing code, CadQuery is the direct fit; if it is interactive sketching and assembly work, FreeCAD is the different category of tool. ### Is CadQuery free to use? Yes. The project is distributed as an open source Python package, and setup.py declares the Apache Public License 2.0 with the licence header in the file and a LICENSE file at the repository root. The repository metadata reports the licence field as NOASSERTION, so the LICENSE file is the authoritative text. ### What is CadQuery? CadQuery is a Python module for building parametric 3D CAD models, built as a library without any GUI and based on the OCCT kernel through the OCP bindings. The README describes it as producing high quality CAD models from short scripts that can be customized. ## Sources - [CadQuery/cadquery on GitHub](https://github.com/CadQuery/cadquery) - [Issues](https://github.com/CadQuery/cadquery/issues) - [Project website](https://cadquery.org) - [README](https://github.com/CadQuery/cadquery/blob/master/README.md) - [Releases](https://github.com/CadQuery/cadquery/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cadquery-cadquery