Skip to main content
shopping_basket Basket 0
Log in

Building a Pi Powered Wireless Label Printer


Combining a Raspberry Pi and a Brother QL-700 to create a self-contained wireless label printer complete with an integrated web based label designer.

Every organised workshop needs labels and with the addition of a Raspberry Pi the low cost Brother QL-700 (840-6302) can be turned into a handy wireless label printer with an integrated designer.

QL Label Printers


The Brother QL label printers come in various configurations. The QL700 model is reasonably compact and can take various different sizes and types of label stock. Thanks to some neat software from Philipp Klaus, it’s now possible to drive them without needing to have official driver support from Brother — meaning that non-x86 platforms can also be used, such as the ARM-based Raspberry Pi. Which of course is perfect for a bolt-on wireless print server — and more!

Let’s take a look at how we’d configure a Pi to drive the QL-700 via a simple web interface.

Installing Raspbian and dependencies

So first we need to write out Raspbian to a Micro SD card. The Lite variant is perfectly sufficient and highly advisable (no need for desktop software etc). Assuming you used a Linux machine to write out the SD card, once this has completed if you remove and reinsert the card so that its partitions get mounted, we can edit a few files.

$ sudo vi /media/<your username>/rootfs/etc/hostname

Change the hostname to something easily remembered, like “labels”.

$ sudo vi /media/<your username>/rootfs/etc/hosts

Then update the hosts file with the same name.

$ sudo touch /media/<your username>/boot/ssh

And create the file that tells Raspbian to enable the SSH server.

Of course, feel free to replace vi with your text editor of choice.

If we now insert the card into our Raspberry Pi and apply power, after a short while we should be able to log in via SSH using mDNS. E.g.

$ ssh pi@labels.local

Alternatively, you could just attach a keyboard and monitor.

Next if we update the system.

$ sudo apt-get update

$ sudo apt-get dist-upgrade

And then install the packaged dependencies with:

$ sudo apt-get install python3-setuptools python3-pip libopenjp2-7-dev libtiff5 git fontconfig

Wireless setup

If you do want to be able to print over a wireless connection instead of wired, you’ll need to also configure the WPA supplicant. If wired Ethernet suits your needs you can skip this step.

To configure the Raspberry Pi to join a wireless network we need to edit a file:

$ sudo vi /etc/wpa_supplicant/wpa_supplicant.conf

And add configuration for the network SSID and passphrase to the bottom of the file. E.g.:


Following which if we save the file and reboot it should join the network. For further details see the documentation on the Raspberry Pi website.

Brother QL printers Python package


The brother_ql Python package provides the foundations for this project and enables driving QL series label printers without the usually required printer drivers. Once this has been installed raster language files can either be generated via your own programs or from image files using the supplied command line utilities. To install this via PIP we simply enter:

$ sudo pip3 install brother_ql

Following which we can take a look at the options for the tool which creates language files which are understood by the printer, from image files, by entering:

$ brother_ql_create --help

One of the nice things about these printers is that they take different sizes of labels, with stock also available as individual labels and on a continuous roll. To list the supported sizes we enter:

$ brother_ql_info list-label-sizes

For details of the options for both of these commands see the GitHub repo.

We had the 62mm wide continuous roll supplied with the printer loaded and so created a PNG file of this width, with the DesignSpark logo centred and a small white border around it


Note that the red background wasn’t present in the image printed and this has just been added to show the image used to scale.

The printer language file was then created with:

$ brother_ql_create --model QL-700 DS_Logo_62mm-wide.png --label-size 62 > DS_Logo.bin

In order to access the printer ports we need to be in the “lp” group and we can add the pi user account to this with:

$ sudo usermod -G lp -a pi

Following which it is necessary to log out and then back in again.

Finally, we can print the generated .bin file with:

$ brother_ql_print DS_Logo.bin /dev/usb/lp0


With the label printed and length cut according to the size of the image file.

Web service label designer


The author of brother_ql has created a very cool piece of software that builds on this to create a standalone web-based label designer, meaning that you can simply point your browser at the Pi, enter some text, set the font and label parameters, and print! To install this we:

$ mkdir src

$ cd src

$ git clone

$ cd brother_ql_web

$ sudo pip3 install -r requirements.txt

$ cp config.example.json config.json

It’s then necessary to edit config.json to set the printer model, along with default label size and fonts etc. It’s also worth changing the server port setting to 80 so that you don’t have to remember some non-standard port number to enter as a URL suffice.

Following minimal configuration we can start this with:

$ sudo python3

Pointing a browser at the pi — e.g. http://labels.local — we should get the user interface and be able to enter text and print.


Final touches

If we’d like this to start automatically at boot we just need to edit /etc/rc.local and before the exit 0 line add:

cd /home/pi/src/brother_ql_web; /usr/bin/python3

Finally, more often than not with something such as this we should configure the Pi such that upon boot it mounts the root filesystem read-only, otherwise we risk filesystem corruption if power is removed without the Pi getting shut down properly. There are various guides that detail how to do this, but one particularly easy solution is to use the rpi-readonly script.

$ git clone

$ cd rpi-readonly

$ sudo ./

This does actually make some serious changes and so, as noted in the GitHub repository, it pays to make a copy of the SD card first.

Andrew Back

Open source (hardware and software!) advocate, Treasurer and Director of the Free and Open Source Silicon Foundation, organiser of Wuthering Bytes technology festival and founder of the Open Source Hardware User Group.


April 23, 2020 12:39


one Question. Is it possible to switch off the engery saving of the Printer using the mudule?
If not is it possible to switch of it by Cups in parallel.
Thanks for answers!


0 Votes

March 20, 2020 15:04

Thank you very much! Nice Tutorial. It inspired me to get a label printer n the first place.
As of now (and in Austria) the QL-800 is more readily available so i went with that one and the tutorial didn't work out of the box.
Here's my two cen'ts on what to do to get it to work with the QL-800: Hope anyone saves a few minutes.
* If /dev/usb/lp0 doesn't show the "Edit Line" Light is probably green on your printer :) (turn it off and use dmesg to find the printer)
* Make sure to get the latest brother_ql:
sudo pip3 install --upgrade
* don't use the deprecated call brother_ql_print
* use brother_ql OPTIONS COMMAND ARGS instead (RTFM is well worth the time)
* a tape that can print red needs the option --red
* My Pi 4b needs all the commands (backend, model, printer) and only woks with backend linux_kernel command) OS Version: 4.19.97-v7l+ #1294 SMP Thu Jan 30 13:21:14 GMT 2020 armv7l GNU/Linux
* with the label ARG use only the width of the tape you have installed, the cut will be done at the correct height anyway (in my case) (e.g.: "--label 62"

0 Votes

June 3, 2019 06:26

Hi everybody, thank you for the tuto. It works realy well with my QL700 on usb, the webserver respond very well. I need to customize the UI (1_adding more buttons and 2_adding a png file for every print). I only need this UI with multiple buttons to label plants I sell on my ecommerce. Anyone could post here some code/explanation to add new buttons who cause the command print with a png and the name of plant varieties.Thanks a lot!

0 Votes

June 3, 2019 07:03

  • Moderated

Hi everybody, thank you for the tutorial. It works really well with my QL700 on USB, the web server responds very well. I need to customize the UI (1_adding more buttons and 2_adding a png file for every print). I only need this UI with multiple buttons to label plants I sell on my e-commerce. Anyone could post here some code/explanation to add new buttons who cause the command print with a png and the name of plant varieties. Thanks!

0 Votes

April 30, 2019 14:47

I can't seem to connect to the QL700. I have it up and running in CUPS service and can print via Windows machines on the network.

But no matter what I change in the config file, I get the following status for the printer:
- undefined -

0 Votes

September 24, 2018 08:30

@Andrew Back nice tutorial but I get the "Need to resize the image..." warning every time I use the brother_ql_create command and after sending that .bin file to the printer, the red led on the printer starts blinking. Any idea? Can you please upload the test image you used?

0 Votes

[Comment was deleted]

[Comment was deleted]

May 29, 2018 07:12

Any chance to provide similar system for Dymo labelwriter 450?

0 Votes

May 30, 2018 13:07

@tomaszm700 , a quick search with Google turned up some pretty good documentation on the Dymo LabelWriter 450. It is controlled over the USB by a very simple data stream of successive lines of bitmapped graphics. Since it sounds (according to the article we are all commenting on) like the brother_ql Python library is writing the labels in raster graphic mode, you could probably modify the library fairly easily to for the label size difference and the output the graphics in the Dymo's raster format instead of the Brother's raster format.
Here is a link to a page with the tech manual for the Dymo:

They also have an SDK available (at least here in the US):

Brother also has technical resources available for the range of other labelers Brother makes. I just picked up a Brother PT-D600 over the weekend. It is limited to a maximum label material width of 24mm (in the short dimension), which isn't big enough for shipping labels. But most of the labels it uses are created by thermal transfer of the "ink" from a donor ribbon inside the cartridge, then laminated. That offers better long-term stability and resistance to environmental conditions than thermal-sensitive paper labels. Brother offers a nice range of specialty label materials, including some durable enough to meet standards for equipment rating labels, labels for cables, and even some heat-shrink material.

The availability of documentation from both manufacturers is refreshing. Both realize that there are many commercial and industrial applications for label printers, and that making it easier for developers to talk to their printers makes more sales likely.

May 23, 2018 11:55

Does it allow you to save the labels? I hate the stock Brother software, and would love to find a better replacement.

0 Votes

May 24, 2018 07:42

@max998 , there are multiple pieces of software mentioned in the article.

The web service label designer (brother_ql_web, mentioned last in the article) doesn't appear (after a quick glance through the source code) to have a mechanism for saving and reloading label designs for later re-use. On the other hand, that software is issued under a GPL license, so you are free to modify it to add such a command.

The other pieces of software involved are command line utilities,
brother_ql_create and brother_ql_print. They work with files, rather than a user interface.

brother_ql_create takes a .png (image) file (which you can generate with whatever tools you wish) and converts it to a file of printer-language commands to generate the corresponding image on a label. You can save this file for later re-use.

brother_ql_print takes the file of printer-language commands and outputs them to the port you specify.

You could definitely use these as building blocks for making your own label library utility.

May 30, 2018 12:52

@BradLevy @max998 Indeed, you could easily create an alternative web interface that allows you to select one of a number of pre-generated labels to print. Or perhaps extend the current web UI to allow saving/restoring.

May 21, 2018 15:10

Good idea , the printer is too big , maybe this one will do the job

0 Votes

May 22, 2018 07:54

@stozek700 , the printers adafruit carries are useful if all you need is printout. Adafruit was unsure what thickness it could handle, which is critical for self-adhesive labels.
If you need smaller labels (as to opposed to a physically smaller printer), Brother does offer a range of label sizes and also non-adhesive paper for the QL-700 printer and its siblings.

Brother also makes label printers that can be controlled by your computer that make more durable laminated labels more appropriate for some needs, like labeling cables, or instrument tags. The labels for that series are available in a number of ink/background color combinations.

May 11, 2018 07:37

I've been considering getting one of these printers or one of its sibling models to meet several labeling needs. The QL-800 (and its wireless-enabled counterpart, the QL-810W) can actual print red and black on the same label. I'll have to look in to the software you mention for using it with the Raspberry Pi!

0 Votes
DesignSpark Electrical Logolinkedin