Gleam Imports

Imports bring functions, types, and values from other modules into your file. Gleam's import system is explicit — nothing is available by default, and everything you use from another module must be imported first.

Basic Import Syntax

import gleam/io
import gleam/string
import gleam/list
import gleam/int

After importing, use the module name as a prefix to access its contents:

io.println("Hello")
string.length("Gleam")
list.map([1,2,3], fn(n) { n * 2 })
int.to_string(42)

Importing Your Own Modules

Import files from your own src/ directory using the path relative to src/:

import user          // src/user.gleam
import order/cart    // src/order/cart.gleam
import utils/format  // src/utils/format.gleam

Import Resolution
──────────────────────────────────────────────────
import user
  └── looks for: src/user.gleam

import order/cart
  └── looks for: src/order/cart.gleam

Use as:
  user.create_user(...)
  cart.add_item(...)

Aliasing an Import

Rename a module at the import site with as:

import gleam/string as str
import gleam/list   as lst
import utils/format as fmt

str.length("hello")   // instead of string.length
lst.map([1,2], ...)   // instead of list.map
fmt.currency(...)     // instead of format.currency

Aliases are useful when two modules have similar names that would be ambiguous, or when a module name is long and used frequently.

Selective Import with Unqualified Access

Import specific names directly into the current scope using curly braces:

import gleam/option.{Some, None}
import gleam/result.{Ok, Error}
import gleam/list.{map, filter, fold}

After this, call the names without a module prefix:

let value = Some(42)      // not option.Some(42)
let empty = None          // not option.None
let doubled = map([1,2,3], fn(n) { n * 2 })

Combining Qualified and Unqualified

import gleam/option.{Some, None} as option

let a = Some(5)                        // unqualified
let b = option.from_result(Ok(10))     // qualified

Importing Types

import product.{type Product}

pub fn display(p: Product) -> String {
  p.name <> ": ₹" <> float.to_string(p.price)
}

Use the type keyword inside the curly braces to import a type name for use in signatures. Constructors are imported separately (without the type keyword):

import shapes.{type Shape, Circle, Rectangle}

let c: Shape = Circle(radius: 5.0)

Import Order Convention

Recommended import order:
──────────────────────────────────────────────────
1. Standard library modules (gleam/...)
2. Third-party package modules
3. Your own project modules

Example:
──────────────────────────────────────────────────
import gleam/io
import gleam/list
import gleam/string
import wisp         // third-party
import my_app/user  // own project
import my_app/order

Avoiding Name Conflicts

Problem: two modules export a function with the same name
──────────────────────────────────────────────────
import my_math
import gleam/int

// Both have a function called "add"
my_math.add(1, 2)   // ← explicit qualifier solves it
int.to_string(3)

Always use qualified module names (module.function) when two imported modules export the same function name. Unqualified imports from both would cause a compile error.

What You Cannot Import

Import Restrictions
──────────────────────────────────────────────────
✗ Private functions (no pub)
✗ Private types
✗ Private constants
✓ pub fn, pub type, pub const
✓ pub opaque type (name only, not internals)

Practical Example — Multi-Module App

// src/app/formatter.gleam
import gleam/string
import gleam/float
import gleam/int

pub fn currency(amount: Float, symbol: String) -> String {
  symbol <> float.to_string(amount)
}

pub fn pad_number(n: Int, width: Int) -> String {
  string.pad_left(int.to_string(n), width, "0")
}

// src/main.gleam
import gleam/io
import gleam/list
import app/formatter.{currency, pad_number}

pub fn main() {
  let prices = [999.99, 1500.0, 49.5]

  prices
  |> list.map(fn(p) { currency(p, "₹") })
  |> list.each(io.println)

  io.println(pad_number(7, 4))   // "0007"
}

Key Points

Import Essentials
──────────────────────────────────────────────────
1. import module/path — qualified access: module.name
2. import module as alias — rename the module
3. import module.{name1, name2} — unqualified access
4. import module.{type TypeName} — import a type name
5. Can combine: import mod.{A, B} as m
6. Only public items can be imported
7. Imports are explicit — nothing is automatic

Explicit imports make every dependency visible at the top of each file. You can read any Gleam file and immediately know which external modules it depends on — making code reviews, refactoring, and debugging significantly easier.