-
-
Notifications
You must be signed in to change notification settings - Fork 13
Installation
Welcome to the official installation guide for PicoForge. This document will help you set up the application on your operating system.
-
Go to the Latest Releases page and download the
picoforge_[version]_[arch]-setup.exefile. -
Locate the downloaded file and run it to install the application.
-
For the application to communicate with your device, the Windows Smart Card service must be running. You can ensure this by running the following command in PowerShell:
Get-Service SCardSvr | Start-Service
Important
Please run the application as Administrator. This is often required for the application to correctly detect and interact with the hardware device.
Warning
The macOS version of this application is tested rarely, while it does work fine, it might have some bugs that I have not experienced, feel free to report it on issues.
If you are a developer or user who can assist with testing and debugging on macOS, contributions are highly appreciated. Please check the Issues tab or join our Discord server.
- Download the application from the Latest Releases.
- No additional driver setup is usually required as the PC/SC framework is built into macOS.
Important
Note on Security: Picoforge images are currently unsigned. You will need to manually authorize the application to run.
- Download the App: Get the latest version from the Releases Page.
- Apple Silicon (M1/M2/M3): Download the arm64 version for native performance.
- Intel Macs: Download the x64 version.
- Authorization (Apple Silicon): Since the app is unsigned, choose one of the following methods to get it running on Apple Silicon:
If you prefer a GUI approach, you can run the Intel version via translation.
- Download the x64 image (e.g., picoforge_0.3.1_x64.dmg).
- Open the file. If prompted, agree to install Rosetta.
- Go to System Settings > Privacy & Security.
- Scroll down to the Security section and click "Open Anyway" for Picoforge.
Use this to run the native arm64 version by stripping the "quarantine" flag.
- Download and extract the arm64 zip file to find picoforge.app.
- Open your Terminal and navigate to the folder containing the app.
- Run the following command to clear the extended attributes:
xattr -cr picoforge.app
- Right-click (or Control-click) the app and select Open.
We offer multiple ways to run the application on Linux. Please choose the method for your distribution.
Regardless of the installation method you choose below, your host operating system must have the Smart Card Daemon (pcscd) installed and running. This service allows the application to talk to the USB device.
# Command may vary by distro, commonly:
sudo systemctl enable --now pcscdTo have the pcscd service, you may need to install pcsc-lite if it is not installed by default on your Linux distribution.
- On Debian :
sudo apt install pcscd - On NixOS, add this line in your /etc/nixos/configuration.nix :
services.pcscd.enable = true;
COPR is the recommended way of installing the application on Fedora.
sudo dnf copr enable lockedmutex/picoforge
sudo dnf install picoforgeIf you prefer to install the .rpm manually, download the picoforge-*.el8.*.rpm (available for x86_64 and aarch64) from the Latest Releases. This RPM is built on EPEL 8 and is compatible with Fedora and all EPEL-based distributions.
sudo dnf install ./picoforge-*.el8.*.rpmsudo dnf install dnf-plugins-core
sudo dnf copr enable lockedmutex/picoforge
sudo dnf install picoforgeNote
For EPEL 8, use yum instead of dnf if dnf is not available.
Troubleshooting: Ensure the EPEL repository is enabled on your system.
sudo zypper addrepo https://copr.fedorainfracloud.org/coprs/lockedmutex/picoforge/repo/opensuse-tumbleweed/lockedmutex-picoforge-opensuse-tumbleweed.repo
sudo zypper refresh
sudo zypper install picoforgesudo zypper addrepo https://copr.fedorainfracloud.org/coprs/lockedmutex/picoforge/repo/opensuse-leap-15.6/lockedmutex-picoforge-opensuse-leap-15.6.repo
sudo zypper refresh
sudo zypper install picoforgeTroubleshooting: Verify the repository URL matches your distribution version.
For manual RPM install, download the picoforge-*.suse.lp156.*.rpm from Latest Releases.
sudo zypper install ./picoforge-*.suse.lp156.*.rpmPicoForge is available via COPR for openEuler 24.
sudo dnf copr enable lockedmutex/picoforge
sudo dnf install picoforgeFor Debian and Ubuntu-based distributions, you can install the application using the .deb package.
- Download the
.debfile from the Latest Releases. - Install dependencies and the package:
Debian / Ubuntu Dependencies
sudo apt update
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libsoup-3.0-0 \
libpcsclite1 pcscd pcsc-tools libhidapi-hidraw0 libsecret-1-0 \
gstreamer1.0-plugins-base libavif16 libwebp7 libenchant-2-2# Example installation command (replace with actual filename)
sudo apt install ./picoforge_[version]_amd64.debFor distributions that do not have a native package or repository (e.g., Arch Linux), you can use AppImage.
AppImage is the recommended way to run PicoForge on unsupported distributions. The format is self-contained and runs on almost any Linux distribution.
- Download the
.AppImagefile from the Latest Releases. - Mark the file as executable:
chmod +x picoforge_*.AppImage - Launch the file:
./picoforge_*.AppImage
Note
If the AppImage does not start, check if you are missing FUSE (Filesystem in Userspace), which is required for AppImages on some newer distributions like Ubuntu 22.04+.
For a better experience, you can use Gear Lever to manage AppImages. It integrates AppImages into your application menu, handles updates, and keeps them organized in a dedicated folder.
Install Gear Lever via Flatpak:
flatpak install flathub it.mijorus.gearleverOnce installed, simply open the downloaded .AppImage file with Gear Lever (or drag and drop it), and it will integrate PicoForge into your system — complete with a desktop entry and icon.
After installation, you can launch picoforge from your application menu or run:
picoforge