Install & Compatibility
Where this runs
tested against v2.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 23.6s · import 0.000s · 1126.4MB
772MB installed
● package 772MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Workplane
✓ from cadquery import Workplane
✗ import cadquery as cq; cq.Workplane(...)
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.
import cadquery as cq
# Define dimensions for a simple box
length = 80.0
height = 60.0
thickness = 10.0
# Create a rectangular box starting on the XY plane
result = cq.Workplane("XY").box(length, height, thickness)
# If running in CQ-editor, 'result' will be automatically displayed.
# For headless use or export, you would typically save it:
# cq.exporters.export(result, "my_box.step")
# This line is for testing/headless environments to confirm an object exists
assert result.isValid()
cadquery --version
Debug
Known issues
breakingCadQuery 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.fixRefer 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`.
affects: All 2.x versions, especially with new Python releases
gotchaWhile `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.fixIf `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).
affects: All versions
gotchaCadQuery'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.fixAlways 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. affects: All 2.x versions
gotchaWhen 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.fixConsult 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.
affects: CadQuery 2.x when used with Jupyter CadQuery v3.3.0 and newer.
deprecatedOlder 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.fixUpdate imports to `import cadquery as cq` and fully qualify calls (e.g., `cq.Workplane`).
affects: Potentially older 1.x and early 2.x examples.
Upgrade
Version history
2.8.0latest on PyPI · released Jun 21, 2026
Audit
Dependencies
OCPrequiredBindings to the OpenCASCADE CAD kernel, fundamental for geometric operations. Distributed as binary wheels.