diff --git a/doc/userscripts.asciidoc b/doc/userscripts.asciidoc
index 97c820898..928315d33 100644
--- a/doc/userscripts.asciidoc
+++ b/doc/userscripts.asciidoc
@@ -15,6 +15,10 @@ mpv, a simple key binding to something like `:spawn mpv {url}` should suffice.
 Also note userscripts need to have the executable bit set (`chmod +x`) for
 qutebrowser to run them.
 
+To call a userscript, it needs to be stored in your data directory under
+`userscripts` (for example: `~/.local/share/qutebrowser/userscripts/myscript`), 
+or just use an absolute path.
+
 Getting information
 -------------------
 
diff --git a/qutebrowser/browser/commands.py b/qutebrowser/browser/commands.py
index 5307d0c8e..dac9edd9a 100644
--- a/qutebrowser/browser/commands.py
+++ b/qutebrowser/browser/commands.py
@@ -948,7 +948,9 @@ class CommandDispatcher:
         useful here.
 
         Args:
-            userscript: Run the command as a userscript.
+            userscript: Run the command as a userscript. Either store the
+                        userscript in ~/.local/share/qutebrowser/userscripts
+                        (or $XDG_DATA_DIR), or use an absolute path.
             verbose: Show notifications when the command started/exited.
             detach: Whether the command should be detached from qutebrowser.
             cmdline: The commandline to execute.
diff --git a/qutebrowser/browser/hints.py b/qutebrowser/browser/hints.py
index fdc2014a4..46eca6b7e 100644
--- a/qutebrowser/browser/hints.py
+++ b/qutebrowser/browser/hints.py
@@ -749,7 +749,10 @@ class HintManager(QObject):
                 - With `spawn`: The executable and arguments to spawn.
                                 `{hint-url}` will get replaced by the selected
                                 URL.
-                - With `userscript`: The userscript to execute.
+                - With `userscript`: The userscript to execute. Either store
+                                     the userscript in
+                                     ~/.local/share/qutebrowser/userscripts (or
+                                     $XDG_DATA_DIR), or use an absolute path.
                 - With `fill`: The command to fill the statusbar with.
                                 `{hint-url}` will get replaced by the selected
                                 URL.
diff --git a/qutebrowser/commands/userscripts.py b/qutebrowser/commands/userscripts.py
index 9f2b0fe10..88ad04d93 100644
--- a/qutebrowser/commands/userscripts.py
+++ b/qutebrowser/commands/userscripts.py
@@ -344,6 +344,13 @@ def run(cmd, *args, win_id, env, verbose=False):
     if user_agent is not None:
         env['QUTE_USER_AGENT'] = user_agent
     cmd = os.path.expanduser(cmd)
+
+    # if cmd is not given as an absolute path, look it up
+    # ~/.local/share/qutebrowser/userscripts (or $XDG_DATA_DIR)
+    if not os.path.isabs(cmd):
+        log.misc.debug("{} is no absolute path".format(cmd))
+        cmd = os.path.join(standarddir.data(), "userscripts", cmd)
+
     runner.run(cmd, *args, env=env, verbose=verbose)
     runner.finished.connect(commandrunner.deleteLater)
     runner.finished.connect(runner.deleteLater)