Skip to main content

Installing AxioCNC on Raspberry Pi

Install AxioCNC on a Raspberry Pi with a desktop (display + keyboard). Use this when the Pi is your main control machine. For headless use, see Raspberry Pi Server.

Choose Your Package​

  • Raspberry Pi 3 / 4 (32‑bit): axiocnc_*_armv7l.deb
  • Raspberry Pi 4 / 5 (64‑bit): axiocnc_*_arm64.deb

Download from GitHub Releases or axiocnc.com.

Steps​

  1. Transfer the .deb to the Pi

    Use scp, a USB drive, or another method. Example:

    scp axiocnc_*_arm64.deb pi@raspberrypi.local:~/

  2. On the Pi, download and install the package

    For Raspberry Pi 4 / 5 (64-bit):

    cd ~
    curl -L -o axiocnc_0.0.89_arm64.deb https://github.com/rsteckler/AxioCNC/releases/download/v0.0.89/axiocnc_0.0.89_arm64.deb
    sudo dpkg -i axiocnc_0.0.89_arm64.deb
    sudo apt-get install -f   # if dependencies are missing

    For Raspberry Pi 3 / 4 (32-bit):

    cd ~
    curl -L -o axiocnc_0.0.89_armv7l.deb https://github.com/rsteckler/AxioCNC/releases/download/v0.0.89/axiocnc_0.0.89_armv7l.deb
    sudo dpkg -i axiocnc_0.0.89_armv7l.deb
    sudo apt-get install -f   # if dependencies are missing

  3. Add your user to the dialout group

    sudo usermod -a -G dialout $USER

    Log out and back in (or reboot) so the change applies.

  4. Run AxioCNC

    axiocnc

    A browser opens at http://localhost:8000. From another device on the network, use http://raspberrypi.local:8000 or http://<pi-ip>:8000.

Verify Serial Access​

groups $USER
ls -l /dev/ttyUSB* /dev/ttyACM*

You should see dialout in your groups and your controller’s device listed.

Auto-Start on Boot (Optional)​

The desktop .deb does not install a systemd unit. To auto-start on boot you must create one, then enable it.

If you use the headless server package instead, the service is already installed. Just run:

sudo systemctl enable axiocnc
sudo systemctl start axiocnc
sudo systemctl status axiocnc

For desktop (this guide), create the service file:

  1. Create /etc/systemd/system/axiocnc.service:

    sudo nano /etc/systemd/system/axiocnc.service

  2. Add (replace pi with your username if different):

    [Unit]
    Description=AxioCNC CNC Controller
    After=network.target

    [Service]
    Type=simple
    User=pi
    ExecStart=/usr/bin/axiocnc
    Restart=always
    Environment="DISPLAY=:0"

    [Install]
    WantedBy=multi-user.target

  3. Enable and start:

    sudo systemctl enable axiocnc
    sudo systemctl start axiocnc
    sudo systemctl status axiocnc

Troubleshooting​

Serial port not found or permission denied

  • Confirm dialout: groups $USER. If missing, run usermod again and log out/in.
  • Check devices: ls -l /dev/ttyUSB* /dev/ttyACM*.

Application won’t start

  • Run axiocnc in a terminal to see errors.
  • Check port 8000: sudo lsof -i :8000. Use axiocnc --port 8001 if 8000 is in use.

Next Steps​