{"id":4464,"library":"cadquery","title":"CadQuery","description":"CadQuery is an intuitive, easy-to-use Python module for building parametric 3D CAD models. It provides a fluent API for creating complex shapes and assemblies, leveraging the OpenCASCADE CAD kernel. Currently at version 2.7.0, it maintains an active development cycle with regular bugfix releases and periodic minor version updates.","status":"active","version":"2.7.0","language":"en","source_language":"en","source_url":"https://github.com/CadQuery/cadquery","tags":["CAD","parametric modeling","scripting","3D","engineering"],"install":[{"cmd":"pip install cadquery","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Bindings to the OpenCASCADE CAD kernel, fundamental for geometric operations. Distributed as binary wheels.","package":"OCP","optional":false}],"imports":[{"note":"While 'from cadquery import *' might work, it can lead to namespace pollution. The convention 'import cadquery as cq' and using 'cq.Workplane' is clearer and safer.","wrong":"from cadquery import *\nresult = Workplane(...)","symbol":"Workplane","correct":"import cadquery as cq\nresult = cq.Workplane(...)"}],"quickstart":{"code":"import cadquery as cq\n\n# Define dimensions for a simple box\nlength = 80.0\nheight = 60.0\nthickness = 10.0\n\n# Create a rectangular box starting on the XY plane\nresult = cq.Workplane(\"XY\").box(length, height, thickness)\n\n# If running in CQ-editor, 'result' will be automatically displayed.\n# For headless use or export, you would typically save it:\n# cq.exporters.export(result, \"my_box.step\")\n\n# This line is for testing/headless environments to confirm an object exists\nassert result.isValid()","lang":"python","description":"This quickstart creates a simple rectangular box using the `Workplane` object, which is the primary entry point for 2D sketching and 3D modeling in CadQuery. The generated `result` object can be viewed in `CQ-editor` or exported to various CAD formats like STEP."},"warnings":[{"fix":"Refer to the official documentation for supported Python versions. Consider using a `conda` environment or `miniforge` for more robust dependency management, as binary wheels for OCP are more reliably distributed via `conda-forge`.","message":"CadQuery has complex dependencies, particularly OCP (OpenCASCADE Python bindings). While Python 3.9 through 3.12 are supported for version 2.7.0, using bleeding-edge Python versions (e.g., newer than 3.12) might encounter lagging support from these underlying dependencies, leading to installation or runtime failures.","severity":"breaking","affected_versions":"All 2.x versions, especially with new Python releases"},{"fix":"If `pip` installation fails, try `conda create -n cqenv python=3.10 && conda activate cqenv && mamba install -c conda-forge -c cadquery cadquery` (using `mamba` for faster resolution).","message":"While `pip install cadquery` is available, the official documentation and community often recommend `conda` (or installing via the `CQ-editor` GUI bundle) for managing CadQuery's complex dependencies. This can prevent common installation issues related to `OCP` on certain operating systems or Python configurations.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always treat `Workplane` operations as returning new objects. For example, `box = cq.Workplane().box(10,10,10)` then `hole_added = box.faces('>Z').hole(5)`. Do not expect `box` to be modified by `hole_added` operations.","message":"CadQuery's API is designed for chaining operations (a 'fluent' API), where most methods return a *new* `Workplane` object. Directly modifying attributes of a `Workplane` or expecting side effects on previous objects in the chain can lead to unexpected behavior. Always assign the result of an operation to a variable if you need to reference that specific state.","severity":"gotcha","affected_versions":"All 2.x versions"},{"fix":"Consult the documentation of your visualization tool. For `Jupyter CadQuery`, explicitly set the `up` parameter in `show_object` (e.g., `show_object(result, up='Z')` or `up='Y'`) to ensure consistent viewing behavior.","message":"When integrating CadQuery with external visualization tools or GUIs like `Jupyter CadQuery`, be aware that the default view orientation (e.g., 'Z-up' vs. 'Y-up' for the 'front' plane) can change between versions of the visualization tool. This can make your models appear rotated or misaligned from expectations if explicit orientation settings are not used.","severity":"gotcha","affected_versions":"CadQuery 2.x when used with Jupyter CadQuery v3.3.0 and newer."},{"fix":"Update imports to `import cadquery as cq` and fully qualify calls (e.g., `cq.Workplane`).","message":"Older CadQuery tutorials or scripts might use direct imports like `from cadquery import Workplane, Vector`, or even `from cadquery import *`. While these may still function, the recommended and more robust practice is to `import cadquery as cq` and access components via `cq.Workplane`, `cq.Vector`, etc. This prevents potential naming conflicts and clearly indicates the source of the objects.","severity":"deprecated","affected_versions":"Potentially older 1.x and early 2.x examples."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}