---
title: "Installation & Setup"
index: 0
---
> [!NOTE]
> Quickshell is still in a somewhat early stage of development.
> There will be breaking changes before 1.0, however a migration guide will be provided.

## Installation

All packages currently track quickshell's master branch. This may change in the future.

### Nix
The Quickshell repo has an embedded flake.
You can use either `git+https://git.outfoxxed.me/outfoxxed/quickshell`
or `github:quickshell-mirror/quickshell`. Use `?ref=` to specify a tag
if you want a tagged release.

```nix
{
  inputs = {
    nixpkgs.url = "nixpkgs/nixos-unstable";

    quickshell = {
      # remove ?ref=v0.1.0 to track the master branch
      url = "git+https://git.outfoxxed.me/outfoxxed/quickshell?ref=v0.1.0";

      # THIS IS IMPORTANT
      # Mismatched system dependencies will lead to crashes and other issues.
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}
```

The package is available as `quickshell.packages.<system>.default`, which you can add to
`environment.systemPackages` or `home.packages` if you use home-manager.

### Arch
Quickshell is available from the aur under
the [quickshell](https://aur.archlinux.org/packages/quickshell) package for the latest release,
or the [quickshell-git](https://aur.archlinux.org/packages/quickshell-git) package
which tracks the master branch.

> [!WARNING]
> When using an AUR package, quickshell may break any time Qt is updated.
> The AUR gives us no way to actually fix this, but Quickshell will attempt to
> warn you if it detects a breakage when updating. If warned of a breakage,
> please reinstall the package

Install using the command below:
```sh
yay -S quickshell
# or
yay -S quickshell-git
```
(or your AUR helper of choice)

### Fedora
Quickshell is available from the [errornointernet/quickshell] COPR, as either
`quickshell` which tracks the latest release or `quickshell-git` which tracks
the master branch.

[errornointernet/quickshell]: https://copr.fedorainfracloud.org/coprs/errornointernet/quickshell

Install using the command below:
```sh
sudo dnf copr enable errornointernet/quickshell

sudo dnf install quickshell
# or
sudo dnf install quickshell-git
```

### Guix
Quickshell's source repository works as a channel. Add the following to your channel list:

```scheme
(channel
  (name quickshell)
  (url "https://git.outfoxxed.me/outfoxxed/quickshell")
  (branch "master"))
```

Then, you can install the package via `guix install quickshell-git` or by adding `quickshell-git` to your system or home definition.

You can also clone the repository and use `guix shell -f quickshell.scm` to try out the package.

### Manual build
See [BUILD.md](https://git.outfoxxed.me/quickshell/quickshell/src/branch/master/BUILD.md)
for build instructions and configurations.

## Editor configuration
If you want to write your own configuration, installing a QML grammar and the LSP is recommended.

Read the [Usage Guide](/docs/guide) after configuring your editor.

> [!NOTE]
> Qmlls versions prior to 6.8.2 do not require `-E`

### Emacs
Install the [yuja/tree-sitter-qml](https://github.com/yuja/tree-sitter-qmljs) tree-sitter grammar,
and the [xhcoding/qml-ts-mode](https://github.com/xhcoding/qml-ts-mode) mode.

Both are packaged for nix via [outfoxxed/nix-qml-support](https://git.outfoxxed.me/outfoxxed/nix-qml-support).

Either `lsp-mode` or `eglot` should be usable for LSP ([caveats below](#language-server)).

The author's personal emacs config uses `lsp-mode` and `qml-ts-mode` as follows:
```elisp
(use-package qml-ts-mode
  :after lsp-mode
  :config
  (add-to-list 'lsp-language-id-configuration '(qml-ts-mode . "qml-ts"))
  (lsp-register-client
   (make-lsp-client :new-connection (lsp-stdio-connection '("qmlls", "-E"))
                    :activation-fn (lsp-activate-on "qml-ts")
                    :server-id 'qmlls))
  (add-hook 'qml-ts-mode-hook (lambda ()
                                (setq-local electric-indent-chars '(?\n ?\( ?\) ?{ ?} ?\[ ?\] ?\; ?,))
                                (lsp-deferred))))
```

### Neovim
Neovim has built-in syntax highlighting for QML, however tree-sitter highlighting
may work better than the built-in highlighting. You can install the grammar
using `:TSInstall qmljs`.

To use the language server ([caveats below](#language-server)),
install [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)
and the following snippet to your configuration:

```lua
require("lspconfig").qmlls.setup {
  cmd = {"qmlls", "-E"}
}
```

### Helix
Helix has built-in syntax highlighting for QML.

To use the language server, add the following snippet to your configuration:

```toml
[language-server.qmlls]
args = ["-E"]
command = "qmlls"
```

### Vscode
1. Install the [Official QML Support extension]
2. Enable the `qt-qml.qmlls.useQmlImportPathEnvVar` setting.
![](/assets/images/vscode-qml-env.png)

[Official QML Support extension]: https://marketplace.visualstudio.com/items?itemName=TheQtCompany.qt-qml

## Language Server
The QML language has an associated language server,
[qmlls](https://doc.qt.io/qt-6/qtqml-tooling-qmlls.html).
We recommend using it, as it will catch a lot of bad practice that may
make your configuration harder to maintain later.

We are aware of the following issues:
- Qmlls does not work well when a file is not correctly structured.
  This means that completions and lints won't work unless braces are closed
  correctly and such.
- Qmlls cannot handle quickshell's singletons. This means you won't see
  completions, and usages of singleton members may show a warning.
  We're still investigating this problem and how to fix it.
- The LSP cannot provide any documentation for Quickshell types.

Keeping in mind the above caveats, qmlls should be able to guide you towards
more correct code should you chose to use it.

> [!NOTE]
> Nix users should note that qmlls will not be able to pick up qml modules
> that are not in `QML2_IMPORT_PATH`. The easiest way to ensure this is by setting
> `qt.enable` to `true` and installing the quickshell package globally.

# Next steps

Create your first configuration by reading the [Intro](/docs/configuration/intro).
