Setup & Dependencies¶

The primary goal is to keep the dependencies of the core package as small as possible. The add-ons are not part of the core package and can therefore use as many packages as needed. The only requirement for these packages is an easy way to install them on Windows, Linux and macOS, preferably as:

pip3 install ezdxf

The packages pyparsing, numpy, fontTools and typing_extensions are the hard dependency and will be installed automatically by pip3!

The minimal required Python version is determined by the latest release version of numpy.

Basic Installation¶

The most common case is the installation by pip3 including the optional C-extensions from PyPI as binary wheels:

pip3 install ezdxf

Installation with Extras¶

To use all features of the drawing add-on, add the [draw] tag:

pip3 install ezdxf[draw]

Tag	Additional Installed Packages
`[draw]`	Matplotlib, PySide6, PyMuPDF, Pillow
`[dev]`	`[draw]` + setuptools, wheel, Cython, pytest (full development setup)

If PySide6 is not available on your system, use PyQt5 by this options:

Tag	Additional Installed Packages
`[draw5]`	Matplotlib, PyQt5, PyMuPDF, Pillow
`[dev5]`	`[draw5]` + setuptools, wheel, Cython, pytest (full development setup)

PySide6 Issue¶

Maybe PySide6 won’t launch on Debian based distributions and shows this error message:

qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
...

This may fix the issue:

sudo apt-get install libxcb-cursor0

Binary Wheels¶

Ezdxf includes some C-extensions, which will be deployed automatically at each release to PyPI as binary wheels to PyPI:

Windows: only amd64 packages
Linux: manylinux and musllinux packages for x86_64 & aarch64
macOS: x86_64, arm64 and universal packages

The wheels are created by the continuous integration (CI) service provided by GitHub and the build container cibuildwheel provided by PyPA the Python Packaging Authority. The workflows are kept short and simple, so my future me will understand what’s going on and they are maybe also helpful for other developers which do not touch CI services every day.

The C-extensions are disabled for pypy3, because the JIT compiled code of pypy is much faster than the compiled C-extensions.

Disable C-Extensions¶

It is possible to disable the C-Extensions by setting the environment variable EZDXF_DISABLE_C_EXT to 1 or true:

set EZDXF_DISABLE_C_EXT=1

or on Linux:

export EZDXF_DISABLE_C_EXT=1

This is has to be done before anything from ezdxf is imported! If you are working in an interactive environment, you have to restart the interpreter.

Installation from GitHub¶

Install the latest development version by pip3 from GitHub:

pip3 install git+https://github.com/mozman/ezdxf.git@master

Build and Install from Source¶

This is only required if you want the compiled C-extensions, the ezdxf installation by pip from the source code package works without the C-extension but is slower. There are binary wheels available on PyPi which included the compiled C-extensions.

Windows¶

Make a build directory and a virtual environment:

mkdir build
cd build
py -m venv .venv
.venv/Scripts/activate.bat

A working C++ compiler setup is required to compile the C-extensions from source code. Windows users need the build tools from Microsoft: https://visualstudio.microsoft.com/de/downloads/

Download and install the required Visual Studio Installer of the community edition and choose the option: Visual Studio Build Tools 20..

Install required packages to build and install ezdxf with C-extensions:

pip3 install setuptools wheel cython

Clone the GitHub repository:

git clone https://github.com/mozman/ezdxf.git

Build and install ezdxf from source code:

cd ezdxf
pip3 install .

Check if the installation was successful:

python3 -m ezdxf -V

The ezdxf command should run without a preceding python3 -m, but calling the launcher through the interpreter guarantees to call the version which was installed in the venv if there exist a global installation of ezdxf like in my development environment.

The output should look like this:

ezdxf 0.17.2b4 from D:\Source\build\.venv\lib\site-packages\ezdxf
Python version: 3.10.1 (tags/v3.10.1:2cd268a, Dec  6 2021, 19:10:37) [MSC v.1929 64 bit (AMD64)]
using C-extensions: yes
using Matplotlib: no

To install optional packages go to section: Install Optional Packages

To run the included tests go to section: Run the Tests

WSL & Ubuntu¶

I use sometimes the Windows Subsystem for Linux (WSL) with Ubuntu 20.04 LTS for some tests (how to install WSL).

By doing as fresh install on WSL & Ubuntu, I encountered an additional requirement, the build-essential package adds the required C++ support and the python3.10-dev package the required headers, change 3.10 to the Python version you are using:

sudo apt install build-essential python3.10-dev

The system Python 3 interpreter has the version 3.8 (in 2021), but I will show in a later section how to install an additional newer Python version from the source code:

cd ~
mkdir build
cd build
python3 -m venv .venv
source .venv/bin/activate

Install Cython and wheel in the venv to get the C-extensions compiled:

pip3 install cython wheel

Clone the GitHub repository:

git clone https://github.com/mozman/ezdxf.git

Build and install ezdxf from source code:

cd ezdxf
pip3 install .

Check if the installation was successful:

python3 -m ezdxf -V

The output should look like this:

ezdxf 0.17.2b4 from /home/mozman/src/.venv/lib/python3.8/site-packages/ezdxf
Python version: 3.8.10 (default, Nov 26 2021, 20:14:08)
[GCC 9.3.0]
using C-extensions: yes
using Matplotlib: no

To install optional packages go to section: Install Optional Packages

To run the included tests go to section: Run the Tests

Raspberry Pi OS¶

Testing platform is a Raspberry Pi 400 and the OS is the Raspberry Pi OS which runs on 64bit hardware but is a 32bit OS. The system Python 3 interpreter comes in version 3.7 (in 2021), but I will show in a later section how to install an additional newer Python version from the source code.

Install the build requirements, Matplotlib and the PyQt5 bindings from the distribution repository:

sudo apt install python3-pip python3-matplotlib python3-pyqt5

Installing Matplotlib and the PyQt5 bindings by pip from piwheels in the venv worked, but the packages showed errors at import, seems to be an packaging error in the required numpy package. PySide6 is the preferred Qt binding but wasn’t available on Raspberry Pi OS at the time of writing this - PyQt5 is supported as fallback.

Create the venv with access to the system site-packages for using Matplotlib and the Qt bindings from the system installation:

cd ~
mkdir build
cd build
python3 -m venv --system-site-packages .venv
source .venv/bin/activate

Install Cython and wheel in the venv to get the C-extensions compiled:

pip3 install cython wheel

Clone the GitHub repository:

git clone https://github.com/mozman/ezdxf.git

Build and install ezdxf from source code:

cd ezdxf
pip3 install .

Check if the installation was successful:

python3 -m ezdxf -V

The output should look like this:

ezdxf 0.17.2b4 from /home/pi/src/.venv/lib/python3.7/site-packages/ezdxf
Python version: 3.7.3 (default, Jan 22 2021, 20:04:44)
[GCC 8.3.0]
using C-extensions: yes
using Matplotlib: yes

To run the included tests go to section: Run the Tests

Manjaro on Raspberry Pi¶

Because the (very well working) Raspberry Pi OS is only a 32bit OS, I searched for a 64bit alternative like Ubuntu, which just switched to version 21.10 and always freezes at the installation process! So I tried Manjaro as rolling release, which I used prior in a virtual machine and wasn’t really happy, because there is always something to update. Anyway the distribution looks really nice and has Python 3.9.9 installed.

Install build requirements and optional packages by the system packager pacman:

sudo pacman -S python-pip python-matplotlib python-pyqt5

Create and activate the venv:

cd ~
mkdir build
cd build
python3 -m venv --system-site-packages .venv
source .venv/bin/activate

The rest is the same procedure as for the Raspberry Pi OS:

pip3 install cython wheel
git clone https://github.com/mozman/ezdxf.git
cd ezdxf
pip3 install .
python3 -m ezdxf -V

To run the included tests go to section: Run the Tests

Ubuntu Server 21.10 on Raspberry Pi¶

I gave the Ubuntu Server 21.10 a chance after the desktop version failed to install by a nasty bug and it worked well. The distribution comes with Python 3.9.4 and after installing some requirements:

sudo apt install build-essential python3-pip python3.9-venv

The remaining process is like on WSL & Ubuntu except for the newer Python version. Installing Matplotlib by pip works as expected and is maybe useful even on a headless server OS to create SVG and PNG from DXF files. PySide6 is not available by pip and the installation of PyQt5 starts from the source code package which I stopped because this already didn’t finished on Manjaro, but the installation of the PyQt5 bindings by apt works:

sudo apt install python3-pyqt5

Use the --system-site-packages option for creating the venv to get access to the PyQt5 package.

Install Optional Packages¶

Install the optional dependencies by pip only for Windows and WSL & Ubuntu, for Raspberry Pi OS and Manjaro on Raspberry Pi install these packages by the system packager:

pip3 install matplotlib PySide6

Run the Tests¶

This is the same procedure for all systems, assuming you are still in the build directory build/ezdxf and ezdxf is now installed in the venv.

Install the test dependencies and run the tests:

pip3 install pytest
python3 -m pytest tests integration_tests

Build Documentation¶

Assuming you are still in the build directory build/ezdxf of the previous section.

Install Sphinx:

pip3 install Sphinx sphinx-rtd-theme

Build the HTML documentation:

cd docs
make html

The output is located in build/ezdxf/docs/build/html.

Python from Source¶

Debian based systems have often very outdated software installed and sometimes there is no easy way to install a newer Python version. This is a brief summery how I installed Python 3.9.9 on the Raspberry Pi OS, for more information go to the source of the recipe: Real Python

Install build requirements:

sudo apt-get update
sudo apt-get upgrade

sudo apt-get install -y make build-essential libssl-dev zlib1g-dev \
   libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
   libncurses5-dev libncursesw5-dev xz-utils tk-dev

Make a build directory:

cd ~
mkdir build
cd build

Download and unpack the source code from Python.org, replace 3.9.9 by your desired version:

wget https://www.python.org/ftp/python/3.9.9/Python-3.9.9.tgz
tar -xvzf Python-3.9.9.tgz
cd Python-3.9.9/

Configure the build process, use a prefix to the directory where the interpreter should be installed:

./configure --prefix=/opt/python3.9.9 --enable-optimizations

Build & install the Python interpreter. The -j option simply tells make to split the building into parallel steps to speed up the compilation, my Raspberry Pi 400 has 4 cores so 4 seems to be a good choice:

make -j 4
sudo make install

The building time was ~25min and the new Python 3.9.9 interpreter is now installed as /opt/python3.9.9/bin/python3.

At the time there were no system packages for Matplotlib and PyQt5 for this new Python version available, so there is no benefit of using the option --system-site-packages for building the venv:

cd ~/build
/opt/python3.9.9/bin/python3 -m venv py39
source py39/bin/activate

I have not tried to build Matplotlib and PyQt5 by myself and the installation by pip from piwheels did not work, in this case the drawing add-on will not work.

Proceed with the ezdxf installation from source as shown for the Raspberry Pi OS.