Skip to content

Raspberry Pi USB Gadget Mode 2026: SSH over USB

Raspberry Pi OS Trixie can present a supported Raspberry Pi as a USB Ethernet adapter. Connect one data-capable USB cable to a laptop, then SSH to the Pi without joining Wi-Fi, scanning a LAN, or attaching a monitor.

For current Trixie images, use the official rpi-usb-gadget workflow instead of old guides that manually edit cmdline.txt, load g_ether, and build USB descriptors. Raspberry Pi documents the feature in USB gadget mode in Raspberry Pi OS: SSH over USB.

When to use USB Gadget Mode

Use case Benefit
Travel or captive-portal Wi-Fi SSH does not depend on the venue network
Workshops and classrooms Each learner connects directly to one Pi
First-boot provisioning Hostname and SSH work before LAN configuration
Recovery Provides an alternate path after Wi-Fi changes
Host internet sharing The laptop can route its connection to the Pi

This guide covers USB Ethernet networking. For flash-drive emulation, see USB OTG mass storage.

Supported models and ports

Model Gadget connection
Zero, Zero W, Zero 2 W Micro-USB port labelled USB, not PWR IN
Raspberry Pi 3A+ USB port that supports device mode
Raspberry Pi 4 and 5 On-board USB-C port
Raspberry Pi 500 and 500+ On-board USB-C port
Compute Module 5 USB-C on the CM5 IO Board
Compute Module 4 Technically possible, but requires additional manual hardware/setup work

When gadget mode uses a dual-role port, that port is not simultaneously available as a normal USB host port for storage, keyboards, or other peripherals.

Use a USB data cable. Charge-only cables can power a board while providing no data connection, which makes the failure look like a software problem.

Power warning

A laptop USB port may not supply enough power for a Raspberry Pi 4 or 5 plus peripherals. Reboots, undervoltage flags, or repeated USB disconnects indicate a power problem.

After connecting, check:

1
2
vcgencmd get_throttled
journalctl -b -k --no-pager | grep -Ei 'under.?voltage|usb|reset|disconnect'

Use a supported externally powered arrangement when the host cannot supply stable power. Do not connect two independent power sources in an improvised way.

Method 1: enable it in Raspberry Pi Imager

Use a current Raspberry Pi Imager and a Raspberry Pi OS Trixie image dated October 2025 or later.

  1. Select the exact Raspberry Pi model.
  2. Select a current Raspberry Pi OS Trixie image.
  3. Choose the target storage device.
  4. Open OS customisation.
  5. Set a unique hostname and username.
  6. Enable SSH and select public-key authentication.
  7. Enable USB Gadget Mode under interfaces/features when offered.
  8. Write and verify the storage device.
  9. Connect the correct OTG/device port directly to the host computer.

The first boot can take longer and may include an expected reboot while initial configuration completes. Wait before assuming that the USB interface failed.

Method 2: enable it on an existing Trixie installation

Verify the operating-system release:

1
2
. /etc/os-release
printf '%s\n' "$VERSION_CODENAME"

Continue when the result is trixie. Install and enable the package:

1
2
3
4
sudo apt update
sudo apt install rpi-usb-gadget
sudo rpi-usb-gadget on
sudo reboot

Enabling gadget mode can interrupt the current network session. Perform the first change with local access or another tested recovery path.

To inspect the command's current options rather than relying on an old article:

1
rpi-usb-gadget --help

Connect with SSH

Try the hostname configured in Imager:

1
ssh your-user@pi-gadget.local

If hostname resolution is unavailable, inspect the USB network adapter on the host. Without internet sharing, the official workflow provides a fallback Pi address of 10.12.194.1:

1
ssh your-user@10.12.194.1

Confirm the server host key from a trusted source on first connection. If a storage device has been reimaged, remove only the obsolete host entry after verifying why the key changed:

1
2
ssh-keygen -R pi-gadget.local
ssh-keygen -R 10.12.194.1

Windows host

Windows uses an RNDIS-compatible USB network path and may need the driver supplied by the Raspberry Pi USB Gadget project.

Check Device Manager for the new network adapter. If it appears as an unknown device, use the driver linked from the official Raspberry Pi article or project repository, not a third-party driver archive.

For internet sharing:

  1. Connect the Pi before enabling Internet Connection Sharing (ICS).
  2. Share the host's working internet adapter to the Raspberry Pi USB adapter.
  3. Wait for address and route negotiation.
  4. If no lease is assigned, disable ICS on all previously shared adapters and re-enable it for the correct USB adapter.

Hyper-V and old USB-network adapters can affect ICS selection. Confirm the interface rather than choosing an Ethernet N name by guesswork.

macOS host

The device should appear as a USB Ethernet interface. To share the Mac's internet connection:

  1. Open System Settings > General > Sharing.
  2. Configure Internet Sharing.
  3. Select the actual upstream connection, such as Wi-Fi.
  4. Select the Raspberry Pi USB Ethernet interface as the destination.
  5. Enable sharing and wait for address negotiation.

Test the direct SSH connection before enabling sharing. This separates basic USB networking failures from routing or DNS failures.

Linux host

Identify the new interface:

1
2
ip -brief link
nmcli device status

Desktop NetworkManager can share an upstream connection to the USB interface. Connection names vary, so inspect them first:

1
nmcli connection show

Do not paste an interface name from another computer. Confirm the device and connection profile on the host you are configuring.

Verify the Pi side

Once connected over SSH:

1
2
3
4
5
ip -brief address
ip route
nmcli device status
systemctl --failed
journalctl -b --no-pager | grep -Ei 'usb|gadget|rndis|ecm'

Test in layers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Local IP stack
ping -c 2 10.12.194.1

# Host or gateway, using the actual route shown by `ip route`
ip route

# Internet routing without DNS
ping -c 2 1.1.1.1

# DNS
getent hosts raspberrypi.com

If direct SSH works but internet access does not, the gadget is working; troubleshoot host sharing, routing, and DNS instead of reinstalling it.

Security checklist

  • Use SSH keys instead of a reusable password.
  • Keep the private key on the host, not on the Pi image.
  • Do not expose the gadget interface through host firewall bridging unintentionally.
  • Treat host internet sharing as routing between security zones.
  • Remove old gadget adapters and stale SSH host keys deliberately.
  • Patch both the host and Raspberry Pi OS.
  • Disable gadget mode if the deployment does not need it.

Apply the broader Raspberry Pi security hardening guide.

Troubleshooting

The Pi powers on but no USB network adapter appears

  1. Confirm that the cable carries data.
  2. Confirm the correct OTG/device port.
  3. Connect directly rather than through a dock.
  4. Confirm Trixie and the package state.
  5. Check the host USB log and Pi kernel log.
1
2
dpkg -l rpi-usb-gadget
journalctl -b -k --no-pager | grep -Ei 'dwc2|gadget|usb'

SSH says connection refused

The network path works, but the SSH server may not be enabled:

1
2
sudo systemctl enable --now ssh
sudo ss -lntp | grep ':22'

.local hostname does not resolve

Use the fallback IP or inspect the host adapter. .local discovery depends on mDNS support, which differs across host systems and managed networks.

Test another data cable and direct host port, disconnect high-power peripherals, and inspect vcgencmd get_throttled. On Pi 4/5, insufficient power is a common cause.

Internet sharing works until the host reconnects

Host operating systems can change interface metrics or sharing state. Recheck the active upstream adapter, USB destination, DHCP lease, route, and DNS after reconnecting.

Disable Gadget Mode

Use the package command rather than removing unrelated boot settings:

1
2
sudo rpi-usb-gadget off
sudo reboot

Confirm the current CLI syntax with rpi-usb-gadget --help, since package interfaces can evolve.

FAQ

Is USB Gadget Mode the same as USB OTG?

USB OTG/device capability is the hardware and controller feature. Gadget Mode is a Linux configuration that exposes a function such as Ethernet or mass storage over that device connection.

Can I use Wi-Fi and USB Ethernet at the same time?

Yes, but route priorities and host internet sharing can affect which path is used. Inspect ip route and NetworkManager rather than assuming traffic uses USB.

Can one cable provide both power and SSH?

Yes on supported ports and hosts, but adequate power is not guaranteed. Raspberry Pi 4/5 deployments may need a supported powered arrangement.

Should I manually add modules-load=dwc2,g_ether?

Not for the standard Trixie rpi-usb-gadget workflow. Manual configuration is for specialised images and requires you to manage descriptors, host compatibility, routing, and upgrades yourself.