Environment Variables Reference¶

Environment variables that affect hyprlax behavior.

hyprlax-Specific Variables¶

HYPRLAX_DEBUG¶

Enable debug output without command-line flag.

Values: 0 (off), 1 (on)
Default: 0

export HYPRLAX_DEBUG=1
hyprlax image.jpg  # Debug enabled

HYPRLAX_TRACE¶

Enable trace-level logging (very verbose).

Values: 0 (off), non-empty (on)

export HYPRLAX_TRACE=1
hyprlax --debug image.jpg

HYPRLAX_VERBOSE¶

Numeric log level override.

Values: 0..4 where 0=error, 1=warn, 2=info, 3=debug, 4=trace

export HYPRLAX_VERBOSE=3  # debug
hyprlax image.jpg

HYPRLAX_INIT_TRACE¶

Enable detailed init-time tracing for argument/config/env processing.

Values: any non-empty string to enable

export HYPRLAX_INIT_TRACE=1
hyprlax --config ./config.toml 2>init-trace.log

Configuration Overrides¶

Environment variables that override config values at startup (CLI still wins):

HYPRLAX_RENDER_FPS — target FPS (e.g., 60, 144)
HYPRLAX_PARALLAX_SHIFT_PIXELS — base shift in pixels (float)
HYPRLAX_ANIMATION_DURATION — animation duration in seconds (float)

Rendering/Performance Tweaks¶

The renderer recognizes the following variables:

HYPRLAX_PERSISTENT_VBO=1 — reuse VBOs to reduce allocations
HYPRLAX_UNIFORM_OFFSET=1 — pass offsets via uniforms (keeps geometry static)
HYPRLAX_NO_GLFINISH=1 — skip glFinish to reduce CPU/GPU sync
HYPRLAX_SEPARABLE_BLUR=1 — enable separable blur path
HYPRLAX_BLUR_DOWNSCALE=<n> — render blur at lower resolution (2, 4, ...)
HYPRLAX_FRAME_CALLBACK=1 — use Wayland frame callbacks for timing
HYPRLAX_RENDER_DIAG=1 — print render diagnostics when idle
HYPRLAX_PROFILE=1 — print frame timing/profile lines

Compositor Detection¶

hyprlax checks these variables to auto-detect your compositor:

HYPRLAND_INSTANCE_SIGNATURE¶

Indicates Hyprland is running.

Set by: Hyprland compositor
Example: v0.35.0-1-g12345abc_1234567890

if [ -n "$HYPRLAND_INSTANCE_SIGNATURE" ]; then
    echo "Running on Hyprland"
fi

SWAYSOCK¶

Indicates Sway is running.

Set by: Sway compositor
Example: /run/user/1000/sway-ipc.1000.12345.sock

if [ -n "$SWAYSOCK" ]; then
    echo "Running on Sway"
fi

WAYLAND_DISPLAY¶

Wayland session identifier.

Set by: All Wayland compositors
Example: wayland-0, wayland-1

if [ -n "$WAYLAND_DISPLAY" ]; then
    echo "Running on Wayland"
fi

Display Variables¶

DISPLAY¶

X11 display (legacy, not used).

Note: X11 support has been removed. This variable is ignored.

XDG_SESSION_TYPE¶

Session type indicator.

Values: wayland, x11, tty
Used for: Confirming Wayland session

if [ "$XDG_SESSION_TYPE" = "wayland" ]; then
    hyprlax image.jpg
fi

Path Variables¶

XDG_CONFIG_HOME¶

User configuration directory.

Default: ~/.config
Used for: Finding config files

# hyprlax looks for configs in:
$XDG_CONFIG_HOME/hyprlax/

XDG_RUNTIME_DIR¶

Runtime directory for sockets.

Default: /run/user/$UID
Used for: IPC socket location (preferred when available)

HYPRLAX_SOCKET_SUFFIX¶

Append a suffix to the IPC socket filename for isolation (useful for tests, parallel runs, or multiple instances).

Values: any short string with letters/digits/-/_
Preferred path: $XDG_RUNTIME_DIR/hyprlax-$USER-$HYPRLAND_INSTANCE_SIGNATURE-$SUFFIX.sock
Fallback path: /tmp/hyprlax-$USER-$SUFFIX.sock

Example:

export HYPRLAX_SOCKET_SUFFIX=tests
make test

Alias: HYPRLAX_TEST_SUFFIX is still accepted but considered deprecated; HYPRLAX_SOCKET_SUFFIX takes precedence when both are set.

HOME¶

User home directory.

Used for: Expanding ~ in paths

Graphics Variables¶

WLR_RENDERER¶

Force wlroots renderer backend.

Values: vulkan, gles2, pixman
Note: May affect performance

export WLR_RENDERER=gles2
hyprlax image.jpg

__GLX_VENDOR_LIBRARY_NAME¶

NVIDIA proprietary driver indicator.

Values: nvidia
Used for: Detecting NVIDIA GPUs

LIBGL_ALWAYS_SOFTWARE¶

Force software rendering.

Values: 0 (off), 1 (on)
Warning: Severely impacts performance

# For testing only
export LIBGL_ALWAYS_SOFTWARE=1
hyprlax --debug image.jpg

Debug Variables¶

WAYLAND_DEBUG¶

Enable Wayland protocol debugging.

Values: 0 (off), 1 (client), 2 (server), 3 (both)
Warning: Very verbose output

export WAYLAND_DEBUG=1
hyprlax image.jpg 2>&1 | less

EGL_LOG_LEVEL¶

EGL debugging verbosity.

Values: debug, info, warning, error, fatal
Default: warning

export EGL_LOG_LEVEL=debug
hyprlax --debug image.jpg

Usage Examples¶

Development Setup¶

#!/bin/bash
# Development environment
export HYPRLAX_DEBUG=1
export WAYLAND_DEBUG=1
hyprlax --config ./test-config.toml test-image.jpg

Production Setup¶

#!/bin/bash
# Production environment
unset HYPRLAX_DEBUG
hyprlax --config ~/.config/hyprlax/production.toml ~/wallpapers/current.jpg

Compositor Override¶

#!/bin/bash
# Force generic mode regardless of compositor
unset HYPRLAND_INSTANCE_SIGNATURE
unset SWAYSOCK
hyprlax --compositor generic image.jpg

Debugging Graphics Issues¶

#!/bin/bash
# Full graphics debugging
export HYPRLAX_DEBUG=1
export EGL_LOG_LEVEL=debug
export WAYLAND_DEBUG=1
hyprlax --debug test.jpg 2>&1 | tee debug.log

Checking Your Environment¶

List Relevant Variables¶

env | grep -E "(HYPRLAX|WAYLAND|HYPRLAND|SWAY|XDG|WLR|EGL|LIBGL)"

hyprlax Environment Check¶

hyprlax --debug --compositor auto test.jpg 2>&1 | head -20

This shows which environment variables hyprlax detected.

Priority Order¶

When multiple configuration methods exist:

Command-line arguments (highest priority)
Environment variables
Configuration file
Built-in defaults (lowest priority)

Example:

export HYPRLAX_DEBUG=1        # Enables debug
hyprlax --debug 0 image.jpg   # Command line overrides, debug disabled

Security Notes¶

IPC socket permissions are not affected by environment variables
Path variables are sanitized before use
Never put sensitive data in HYPRLAX_DEBUG output