clojure.core/require

View this page on ClojureDocs

Type: function Added: Clojure 1.0 Examples: 10 Runnable: 4

([& args])

Loads libs, skipping any that are already loaded. Each argument is either a libspec that identifies a lib, a prefix list that identifies multiple libs whose names share a common prefix, or a flag that modifies how all the identified libs are loaded. Use :require in the ns macro in preference to calling this directly.

Libs

A 'lib' is a named set of resources in classpath whose contents define a library of Clojure code. Lib names are symbols and each lib is associated with a Clojure namespace and a Java package that share its name. A lib's name also locates its root directory within classpath using Java's package name to classpath-relative path mapping. All resources in a lib should be contained in the directory structure under its root directory. All definitions a lib makes should be in its associated namespace.

'require loads a lib by loading its root resource. The root resource path is derived from the lib name in the following manner: Consider a lib named by the symbol 'x.y.z; it has the root directory /x/y/, and its root resource is /x/y/z.clj, or /x/y/z.cljc if /x/y/z.clj does not exist. The root resource should contain code to create the lib's namespace (usually by using the ns macro) and load any additional lib resources.

Libspecs

A libspec is a lib name or a vector containing a lib name followed by options expressed as sequential keywords and arguments.

Recognized options: :as takes a symbol as its argument and makes that symbol an alias to the lib's namespace in the current namespace. :as-alias takes a symbol as its argument and aliases like :as, however the lib will not be loaded. If the lib has not been loaded, a new empty namespace will be created (as with create-ns). :refer takes a list of symbols to refer from the namespace or the :all keyword to bring in all public vars.

Prefix Lists

It's common for Clojure code to depend on several libs whose names have the same prefix. When specifying libs, prefix lists can be used to reduce repetition. A prefix list contains the shared prefix followed by libspecs with the shared prefix removed from the lib names. After removing the prefix, the names that remain must not contain any periods.

Flags

A flag is a keyword. Recognized flags: :reload, :reload-all, :verbose :reload forces loading of all the identified libs even if they are already loaded (has no effect on libspecs using :as-alias) :reload-all implies :reload and also forces loading of all libs that the identified libs directly or indirectly load via require or use (has no effect on libspecs using :as-alias) :verbose triggers printing information about each load, alias, and refer

Example:

The following would load the libraries clojure.zip and clojure.set abbreviated as 's'.

(require '(clojure zip [set :as s]))

Examples

by scode on 2010-07-15 . May have evaluation errors. ▶

;; Require clojure.set and call its union function: (require 'clojure.set) nil (clojure.set/union #{1} #{2}) #{1 2}

by teyc on 2010-09-08 . May have evaluation errors. ▶

;; alias clojure.java.io as io (require '[clojure.java.io :as io]) nil (io/file "Filename") #<File Filename> ;; alias clojure.java.io as io using prefixes (require '(clojure.java [io :as io2])) nil (io2/file "Filename") #<File Filename>

by boxie on 2010-11-10 ▶

(ns rosettacode.24game (:require [clojure.string :as str])) (defn parse-infix-data "input '1+2+3+4' output (1 + 2 + 3 + 4) where the numbers are clojure numbers, and the symbols are clojure operators" [string] (map read-string (next (str/split string #""))))

by lambder on 2011-09-02 . May have evaluation errors. ▶

(require '(clojure.contrib [sql :as sql]))

by devn on 2013-01-20 ▶

(ns myproject.core (:use [clojure.core] :reload) (:require [clojure.string :as str :refer [replace]] :reload-all)) (str/replace "foo" #"o" "e") "fee" ; similar but using a prefix. (ns myproject.core (:require (clojure [core] [string :as str :refer [replace]] )))

by ichisemasashi on 2016-12-21 . May have evaluation errors. ▶

; rename a function name (thanks for @noisesmith) ; rename 'clojure.repl/doc' to 'd' (require '[clojure.repl :as r :refer [doc] :rename {doc d}]) nil (d doc) ------------------------- clojure.repl/doc ([name]) Macro Prints documentation for a var or special form given its name nil

by jafingerhut on 2020-12-16 ▶

;; Note that require is known _not_ to be thread safe in Clojure 1.11.x and ;; earlier, so avoid calling it concurrently from multiple threads. ;; See https://ask.clojure.org/index.php/9893/require-is-not-thread-safe ;; for some thoughts on approaches to using require from multiple threads ;; safely, which today boils down to "use locks to make all calls to require ;; guaranteed to execute one at a time".

by PEZ on 2022-06-01 . May have evaluation errors. ▶

;; Watch out for the Gilardi scenario: https://technomancy.us/143 ;; If you need to refer to the required symbols in the same block ;; of code as it is being defined, that will only work at top level ;; and in top-level `do`: (do (require '[clojure.set :as c-set]) (c-set/union #{1} #{2})) ; => #{"1" "2"} ;; It won't work here, because the compiler does not know about ;; `c-set` when it tries to compile the form: (->> ["1" "2"] (reduce (fn [acc v] (require '[clojure.set :as c-set]) (c-set/union acc #{v})) #{})) ; => Syntax error compiling at ... ; No such namespace: c-set ;; A solution is to move the use of the required symbol to run-time. ;; E.g. with `resolve`: (->> ["1" "2"] (reduce (fn [acc v] (require '[clojure.set :as c-set]) ((resolve 'c-set/union) acc #{v})) #{})) ; => #{"1" "2"} ;; At which point `requiring-resolve` might be clearer: (->> ["1" "2"] (reduce (fn [acc v] ((requiring-resolve 'clojure.set/union) acc #{v})) #{})) ; => #{"1" "2"}

by imrekoszo on 2022-06-02 ▶

;; As a follow-up to previous examples, one more reason to prefer using ;; `requiring-resolve` from within runtime functions when possible, is that it ;; wraps `require` in a thread-safe way (require itself is not thread-safe as of ;; 1.11.1 as mentioned in an earlier example). ;; This is done via the private function `clojure.core/serialized-require` ;; Some more info can be found in the comment at ;; https://ask.clojure.org/index.php/9893/require-is-not-thread-safe?show=9902#c9902

by eval on 2023-10-27 . May have evaluation errors. ▶

;; :as-alias (introduced in v1.11) allows you to create an alias without loading ;; the namespace. Typically, when using :as-alias, the namespace is just used as a ;; qualifier and is not a loadable namespace. (require '[company.some-widget.some-entity :as-alias some-entity]) ;; As with regular aliases it's now more convenient to create maps {::some-entity/id "some-id"} {:company.some-widget.some-entity/id "some-id"} ;; ...to destructure (defn find-some-entity-by-id [{::some-entity/keys [id]}] ,,,) ;; ...or to register specs (s/def ::some-entity/id string?)

Note by gstamp

Good description of use/require/import here:

http://blog.8thlight.com/articles/2010/12/6/clojure-libs-and-namespaces-require-use-import-and-ns

See also

• clojure.core/remove-ns (0)
• clojure.core/import (2)
• clojure.core/use (1)
• clojure.core/ns (3)
• clojure.core/refer (1)
• clojure.core/requiring-resolve (0)
• clojure.core/resolve (4)

---

Content from the matching ClojureDocs page, with authors credited on each contribution.