Intro To CadQuery Series: Installing CQ-Editor

In this article you’ll learn about how to install CQ-Editor, the CadQuery IDE. If you follow along, by the end of this article you’ll be all set up and taking your first steps by creating your first CadQuery model.

What is CQ-Editor?

CQ-Editor is an Integrated Development Environment (IDE) for designing in CadQuery. It is one of several solutions which help you to visualize and debug your CadQuery models, but I have chosen it to introduce CadQuery because it provides a number of key tools to help users get a kickstart creating designs, including:

– A code editor for creating your model in python
– A 3D viewport to visualize your design
– A debugger + variable viewer to help troubleshoot your design

Both CadQuery and CQ-Editor are currently under active development, so the installation process is not yet perfectly streamlined. Below I will describe my process for setting up CQ-Editor in a bit more detail than the README (which you should read, it contains a ton of essential information!). Follow along, and we’ll have you up and running in no time.

Installing CQ-Editor (The Easy Way):

For those who do not wish to install and setup a Python environment to run the CQ-Editor source code (which is a lot easier than it sounds, I promise! See below for more info…) there are precompiled releases of CQ-Editor that are as simple as download and run.

As mentioned above, CQ-Editor is still under active development at the time I am writing this article. Unfortunately, the current release of CQ-Editor on the main Github repository is very out of date and should not be used (@V0.2; article last updated: 09/2022).

Instead you should go to a fork of the core repository made by jmwright where you can download a working release of CQ-Editor. You will need a Github account. Once logged in to Github, simply navigate to the above link, click the first build entry with a green checkmark, scroll to the bottom, and download the release for your OS under the header Artifacts (see video below). Once your download is complete, unpack the archive, and run the script in the root folder. You made it! You can skip over the next few sections if you’d like, as they will be covering an alternative approach to installing CQ-Editor.

I’ve had it with all these #!@*&% snakes!
_{(AKA how to install CQ-Editor with conda)}

So, you want to install and run CadQuery from source, welcome! I promise, it’s not as scary as it may sound. This approach will give you a lot more flexibility and freedom. You can install whatever libraries/plugins you’d like, or even edit the source code. If you’re looking to contribute to the development of CQ-Editor, this is also the approach for you!

CadQuery and CQ-Editor are written in Python, a great langauge for this kind of application, but nonetheless sometimes a bit of a beast to get setup. This becomes particularly clear when it comes to wrangling python versions and dependencies. There are many solutions that are currently available (venv, pipenv, poetry, conda) to address this problem in one way or another. CadQuery primarily uses Anaconda (conda), a cross-platform, popular, and well-supported distribution of Python with its own dependency management system built-in. For those new to Python or a bit rusty, using Conda can be a bit challenging to get right at first. For this reason I’m going to start by walking you through getting up and running with Conda. If you’ve already got Conda up and running you can probably skip this section!

Anaconda is primarily oriented to Python users who work in Data Science, and thus the full version of the Anaconda distribution comes bundled with a number of common libraries for this purpose already installed. If you do this kind of work, it’s a great perk and allows you to get up and running quickly. For someone who is installing conda primarily to install CadQuery, the full Anaconda installation comes with a lot of unecessary functionality, that will take up a bunch of your disk-space. If this applies to you, I recommend using Miniconda which includes a Python distribution, conda (for dependency management), and a few core packages to support these base features without all the excess bloat. Clicking the above link will bring you to a page where you will pick the latest installer compatible with your OS, and download!

Note: For Windows users, I recommend you Select both “Add Miniconda to my PATH” and “Register Miniconda as my default” as long as you plan to use this as your primary Python distribution on the machine. This will make things easier and more streamlined (in my opinion). If you wish to use other Python distributions alongside Miniconda, selecting this may cause conflicts, and should only be done at your own peril.

Installing CQ-Editor (Conda)

Now that you have conda running on your machine, you will need to download the CQ-Editor source code. If you’re going this route, you’ll most likely want to download the latest development version of CQ-Editor. The best way is to use git (git clone https://github.com/jmwright/CQ-editor.git), however you can also download a zip of the repository. If necessary extract the source code, and then navigate into the root folder of the project (cd ./CQ-Editor).

Now we need to install the project’s dependencies so we can run the source code. We will use conda to create a Python virtual environment (venv) in which we will store our CadQuery dependencies. This approach with a venv is prefered over installing into the global/root environment, as it allows us to download the complete set of libraries compatible with CQ-Editor without interfering with any dependencies which may be installed for other projects (for example).

Before we start installing dependencies into our venv, we have the opportunity to add in any additonal dependencies which we may need for our work in CadQuery. For new users, this may not be necessary now but it is something you may want to come back to later! There aren’t a ton of plugins available quite yet, but there are definitely some great additions to the core proejct you might want, and I expect the number will continue to grow along with the growing community of users! There are a few places to look for plugins, including the “Awesome Cadquery” page, and the official list of plugins. A special shoutout to the plugin cq-warehouse, which has a ton of great functionality all in one place.

To add additional dependencies we will be editing cqgui_env.yml. Adding dependencies is easy:

– If the dependency is able to be retreived from conda (typically the dependency will suggest installing using conda in the README) then all you must do is add a new line under dependencies.

– If the dependency is only available on pip, then you will need to add pip as a conda dependency (as described above), and then list the pip dependencies as shown in the example below.

#Example cqgui_env.yml file
name: cqgui
channels:
  - CadQuery
  - conda-forge
dependencies:
  - pyqt=5
  - pyqtgraph
  - python=3.10
  - spyder=5
  - path
  - logbook
  - requests
  - cadquery=master
  #Add pip as a conda dep
  - pip
  #List out all your pip deps (here we use github URLs, but package names work as well)
  - pip:
    - git+https://github.com/gumyr/cq_warehouse.git#egg=cq_warehouse
    - git+https://github.com/CadQuery/cadquery-plugins.git#egg=teardrop&subdirectory=plugins/teardrop
    - git+https://github.com/meadiode/cq_gears.git@main

Now it’s time to let conda work its magic, run:
conda env create -f cqgui_env.yml -n cqgui || conda env update -f cqgui_env.yml -n cqgui

The first half of this command attempts to create a new conda environment named cqgui which will contain the dependencies defined in cqgui_env.yml. If this environment already exists, then the first half will return an error, leading to the second half of the command being run (if the first half succeeds, the second half is just skipped). The second half of the command instead updates the existing environment named cqgui to match the dependencies outlined in cqgui_env.yml. This make take a handful of minutes, but once done you’re ready to get things running.

In the root folder of the CQ-Editor source code, run:
conda activate cqgui && python run.py

This command will activate the conda venv we just created and then run the CQ-Editor run.py file in this venv to start up the IDE.

I suggest making a pair of scripts (.bat/.sh) to run these two commands (see here for an example). I am running CQ-Editor in windows so I created a simple CQEditor.bat file, which I then pinned to my Start Menu/Desktop/Taskbar for easy access.

First Steps in CQ-Editor:

You made it! If you’ve gotten here, hopefully you’re now staring at your shiny new CQ-Editor. Take a few moments to explore, and then we’ll jump in to making your first object:

References:

Below are some of the key resources that you should review as you get started working with CadQuery in CQ-Editor:

– CadQuery Documentation: visit to get acquainted with the philosophy and approach to designing in CadQuery
– CadQuery Examples: I highly recommend you work through this list of examples, as it will help acquaint you with the approach to the most common modeling tasks in CadQuery
– CadQuery Cheatsheet: A resource which allows you to see the most common CadQuery functions all in one place! A handy companion to keep by your side on your explorations of CadQuery.
– CadQuery API Reference: Use this page as a table of contents for the core CadQuery functions, click each one to get a full overview of their parameters.

Conclusions:

Congrats on your first steps in CadQuery with CQ-Editor. Stay tuned for the next article in our series to learn more about designing real-world models in CadQuery. Happy making!