Clojure Namespaces Guide — Require, Use, Import, and Code Organization

In this tutorial, you will learn about Clojure Namespaces Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Clojure namespaces are managed by the ns macro with :require (load and alias), :use (import all but deprecated), :import (Java interop), and :refer (specific symbols) -- providing modular code organization and dependency management.

Basic Namespace

(ns my-app.core
  (:require [clojure.string :as str]
            [clojure.set :as set])
  (:import [java.util Date Calendar])
  (:refer-clojure :exclude [get]))

;; Use required namespace
(str/join ", " [1 2 3])    ;; "1, 2, 3"
(set/union #{1 2} #{2 3})   ;; #{1 2 3}

;; Use imported Java class
(Date.)

Require Options

;; :as - alias the namespace
(ns my-app.core
  (:require [clojure.string :as str]))

;; :refer :all - import all symbols (discouraged)
(ns my-app.core
  (:require [clojure.string :refer :all]))

;; :refer - import specific symbols
(ns my-app.core
  (:require [clojure.string :refer [join split]]))

;; :rename - rename imported symbols
(ns my-app.core
  (:require [clojure.string :as str
             :rename {join str-join, split str-split}]))

Creating Namespaces

;; Define a namespace
(ns my-app.utils)

(defn trim [s]
  (clojure.string/trim s))

;; In other file
(ns my-app.main
  (:require [my-app.utils :as utils]))

(utils/trim "  hello  ")

Java Interop

;; Import Java classes
(ns my-app.java
  (:import [java.io File BufferedReader FileReader]
           [java.util HashMap ArrayList]))

;; Use Java objects
(def f (File. "/tmp/test.txt"))
(.exists f)         ;; method call
(.length f)         ;; property access
(.getName f)

;; doto for chaining
(doto (ArrayList.)
  (.add "first")
  (.add "second"))

;; memfn for method references
(map #(.toUpperCase %) ["a" "b"])  ;; ("A" "B")

Common Mistakes

1. Using :use instead of :require

:use is deprecated. Use :require ... :refer instead. :use pollutes the namespace.

2. Circular namespace dependencies

Namespace A requires B, and B requires A. This causes compilation errors. Extract shared code into a third namespace.

3. Forgetting to require

Calling (str/join ...) without requiring clojure.string causes a compiler error.

Practice Questions

1. How do you require a namespace with an alias? (:require [namespace :as alias]). Then use alias/symbol.

2. How do you import specific symbols from a namespace? (:require [namespace :refer [sym1 sym2]]). Only those symbols are available directly.

3. How do you import a Java class? (:import [java.io File]) then (File. "/path").

FAQ

{{< faq question="What is the default namespace?" >}} The user namespace. The REPL starts in user. Your code files define their own namespaces with ns.

{{< /faq >}}

{{< faq question="How do I reload a namespace?" >}} In the REPL: (require 'my.namespace :reload) or (require 'my.namespace :reload-all) for recursive reload.

{{< /faq >}}

{{< faq question="Can I create dynamic namespaces?" >}} Yes. (create-ns 'dynamic.ns) and (intern ns sym value) create namespaces programmatically. {{< /faq >}}

What's Next

Now learn about protocols and records.