Installation

Download the desktop app for macOS, Windows, or Linux. Or self-host with Docker or a manual Python setup.

Some features on this page require the Full Version.

The Needlework Studio login screen

System Requirements

• macOS — macOS 11 (Big Sur) or later. Available for both Apple Silicon and Intel processors.
• Windows — Windows 10 or later (64-bit).
• Linux — Ubuntu 20.04, Debian 11, or equivalent (64-bit). Available as AppImage (universal) and .deb package.
• Docker — Any system running Docker Engine 20.10 or later.
• Manual Setup — Python 3.10 or newer.

Desktop App

Pre-built desktop installers are available on the Downloads page. Download the appropriate package for your operating system:

• macOS (Apple Silicon) - .dmg disk image (ARM64). For M1/M2/M3/M4 Macs. Open the DMG and drag Needlework Studio into your Applications folder.
• macOS (Intel) - .dmg disk image (x64). For older Intel-based Macs. Open the DMG and drag Needlework Studio into your Applications folder.
• Windows - .exe installer. Run the installer and follow the on-screen prompts.
• Linux - .AppImage portable executable. Mark the file as executable (chmod +x) and run it directly.
• Linux (.deb) - .deb package for Debian and Ubuntu. Install with sudo apt install ./needlework-studio_*.deb.

Local Data Storage

The desktop app stores all data locally on your machine. No server or internet connection required. Your thread inventory, patterns, and project data stay in the application's data directory on disk.

Docker

Docker is the recommended way to self-host Needlework Studio. A single container runs the full application with persistent data stored in a Docker volume.

Quick Start

Pull the latest image from the GitHub Container Registry:

docker pull ghcr.io/greenglasst/needleworkstudio:latest

Docker Compose

Create a docker-compose.yml file with the following configuration:

services:
  needlework-studio:
    image: ghcr.io/greenglasst/needleworkstudio:latest
    ports:
      - "6969:6969"
    volumes:
      - needlework-data:/data
    environment:
      # - ADMIN_USERNAME=your_username
    restart: unless-stopped

volumes:
  needlework-data:

Start the container:

docker compose up -d

Create Your First User

After starting the container, create an initial user account with the built-in management script:

docker compose exec needlework-studio python3 manage_users.py create

Follow the interactive prompts to set a username, email (must contain @), and password (with confirmation). Once created, promote the account to admin so you can manage other users from the web admin panel:

docker compose exec needlework-studio python3 manage_users.py admin

Alternatively, you can set the ADMIN_USERNAME environment variable in your docker-compose.yml to automatically promote a user to admin on startup (see the Docker Compose example above).

Open http://localhost:6969 in your browser and log in.

Manual Python Setup

If you prefer to run Needlework Studio directly on a host machine without Docker, you can set it up manually with Python.

Prerequisites

• Python 3.10 or newer - verify with python3 --version.
• pip - the Python package installer (usually bundled with Python).

Clone and Install

Clone the repository and set up a virtual environment:

# Contact support for source access
cd NeedleworkStudio
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Initialize the Database

Run the database initialization script to create all tables and seed the thread library:

python3 init_db.py

This seeds the database with 744 DMC threads and over 400 Anchor threads.

Create a User

Create your first user account:

python3 manage_users.py create

Follow the interactive prompts to set a username, email (must contain @), and password (with confirmation). Once created, promote the account to admin so you can manage other users from the web admin panel:

python3 manage_users.py admin

Run the Application

For development or local testing, start the application directly with Python:

python3 app.py

The application will be available at http://localhost:6969.

Production with Gunicorn

For production deployments, use Gunicorn as the WSGI server:

gunicorn -w 1 --threads 4 -b 0.0.0.0:6969 app:app

Important: You must use a single worker (-w 1). Needlework Studio uses an in-memory rate limiter that is not shared across processes. Running multiple workers would cause each worker to maintain its own independent rate-limit counters, making the rate limiting ineffective. The --threads 4 flag provides concurrency within that single worker to handle multiple simultaneous requests.