Download & Install

This page will guide you through downloading, installing, and launching Elftia for the first time.

System Requirements

Before installing, please ensure your device meets the following minimum requirements:

Platform	Minimum Version	Architecture
Windows	Windows 10 (64-bit) or later	x64 / arm64
macOS	macOS 10.15 (Catalina) or later	Intel / Apple Silicon
Linux	Ubuntu 20.04 / Fedora 36 / Debian 11 or equivalent	x64

Hardware Recommendations:

• RAM: 4 GB or more (8 GB recommended)
• Disk Space: At least 500 MB of available space
• Network: Internet connection required to call LLM APIs

Optional Dependencies (required for Agent features):

Elftia will automatically detect the following tools on first launch. If you plan to use Agent features (code editing, file operations, Shell commands, etc.), it's recommended to install them beforehand:

Tool	Purpose	Download
Node.js 18+	MCP server runtime, some tool execution	nodejs.org
Git	Version control, project management	git-scm.com
uv / uvx	Python package management (required by some MCP servers)	astral.sh/uv

These dependencies are optional — if you only need basic AI chat functionality, you can skip them.

Download

Official Website

Visit the Elftia official website download page and select the version for your operating system.

GitHub Releases

You can also download the latest or previous versions from the GitHub Releases page. Each release includes the following installers:

Platform	Installer Format	Example Filename
Windows	NSIS Installer	Elftia-Setup-x.x.x.exe
macOS	DMG Image	Elftia-x.x.x.dmg / Elftia-x.x.x-arm64.dmg
Linux	AppImage	Elftia-x.x.x.AppImage

Installation Steps

Windows

1. Double-click the downloaded Elftia-Setup-x.x.x.exe file.
2. If a Windows SmartScreen prompt appears, click "More info" and then select "Run anyway".
3. Choose the installation path (default is C:\Users\<username>\AppData\Local\Elftia).
4. Wait for the installation to complete. The installer will automatically create a desktop shortcut and Start Menu item.
5. Click "Finish" to launch Elftia.

tip

Elftia uses NSIS installer with automatic update support. The installed application can be uninstalled normally through system settings.

macOS

1. Double-click the downloaded .dmg file to mount the disk image.
2. In the opened window, drag the Elftia icon into the "Applications" folder.
3. On first launch, macOS may show a "Cannot verify developer" prompt:
   • Open "System Preferences → Security & Privacy → General"
   • Click the "Open anyway" button
4. Elftia will launch and be ready to use.

tip

Apple Silicon (M1/M2/M3/M4) users should download the arm64 version for optimal performance. Intel Mac users should download the standard version.

Linux

1. Download the .AppImage file.
2. Grant execute permission:

   chmod +x Elftia-x.x.x.AppImage

3. Double-click to run or execute in terminal:

   ./Elftia-x.x.x.AppImage

tip

If AppImage fails to run, you may need to install FUSE: sudo apt install libfuse2 (Ubuntu/Debian).

First Launch

When launching Elftia for the first time, you will see the following flow:

1. Environment Detection

Elftia will automatically detect installed tools on your system (Node.js, Git, ripgrep, uv/uvx, etc.). Detection results will be displayed in the "Environment" section of the Settings page, with green (installed) or red (not installed) status indicators next to each tool.

You can view and manage these tools later in Settings → General → Environment. Some missing tools can be installed directly by clicking the "Install" button.

2. Language Selection

Elftia supports three interface languages:

• Simplified Chinese
• English
• Japanese

The default language is automatically selected based on your system language. You can change it anytime in Settings → General → Language.

3. Configure LLM Providers

To start using AI chat, you need to configure at least one LLM provider. See First Chat for details.

Steam Version Differences

If you install Elftia through Steam, note the following differences:

Item	Standard Edition	Steam Edition
Update Method	Automatic in-app updates (electron-updater)	Updates via Steam client
Installation Path	User-defined	Steam library folder
Uninstall Method	System Settings / Control Panel	Uninstall via Steam
Features	Identical	Identical

The Steam version has identical features to the standard edition; only the update mechanism differs.

Common Installation Issues

Installer won't run

Windows: Check if blocked by antivirus software. Some antivirus programs may incorrectly flag Electron applications. Add Elftia to your antivirus whitelist.

macOS: If you see "damaged, can't be opened" message, run in terminal:

xattr -cr /Applications/Elftia.app

Linux: Confirm FUSE dependencies are installed and the file has execute permissions.

Blank screen or crash on startup

• Ensure graphics drivers are updated to the latest version.
• Try running with administrator privileges (Windows).
• Check if another Elftia instance is already running and close it.
• If using older GPU, try adding --disable-gpu parameter on startup.

Missing .NET or Visual C++ runtime (Windows)

Some Windows systems may lack necessary runtime libraries. Install Visual C++ Redistributable and retry.

Firewall blocking internet connection

Elftia needs internet access to call LLM APIs. Ensure your firewall allows Elftia's outbound connections. For proxy setup, see Using Proxy.

---

After installation is complete, continue reading First Chat to begin your AI journey.