package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (31)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. R
    Raphaël Proust <code@bnwr.net>
  2. Anton Bachin

Sources

6.0.0-alpha00.tar.gz
md5=8a88c5d5fcb01d179bbb12e6b6888dca
sha512=bfecd3fa0a3461a3368bd7724e2fce7a751ba3899d590d5b08bc4257b058ca34ec25de1a3ead6585528afe77c6ca6db1c3e2d2421d6a773c845ef091472d2ed9

Description

A promise is a value that may become determined in the future.

Lwt provides typed, composable promises. Promises that are resolved by I/O are resolved by Lwt in parallel.

Meanwhile, OCaml code, including code creating and waiting on promises, runs in a single thread by default. This reduces the need for locks or other synchronization primitives. Code can be run in parallel on an opt-in basis.

Published: 24 Jul 2025

README

Lwt

version GitHub Actions status

Lwt is a concurrent programming library for OCaml. It provides a single data type: the promise, which is a value that will become determined in the future. Creating a promise spawns a computation. When that computation is I/O, Lwt runs it in parallel with your OCaml code.

OCaml code, including creating and waiting on promises, is run in a single thread by default, so you don't have to worry about locking or preemption. You can detach code to be run in separate threads on an opt-in basis.

Here is a simplistic Lwt program which requests the Google front page, and fails if the request is not completed in five seconds:

open Lwt.Syntax

let () =
  let request =
    let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = Lwt_unix.((List.hd addresses).ai_addr) in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      let* () = write outgoing "GET / HTTP/1.1\r\n" in
      let* () = write outgoing "Connection: close\r\n\r\n" in
      let* response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let* () = Lwt_unix.sleep 5. in
    Lwt.return None
  in

  match Lwt_main.run (Lwt.pick [request; timeout]) with
  | Some response -> print_string response
  | None -> prerr_endline "Request timed out"; exit 1

(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)

In the program, functions such as Lwt_io.write create promises. The let* ... in construct is used to wait for a promise to become determined; the code after in is scheduled to run in a "callback." Lwt.pick races promises against each other, and behaves as the first one to complete. Lwt_main.run forces the whole promise-computation network to be executed. All the visible OCaml code is run in a single thread, but Lwt internally uses a combination of worker threads and non-blocking file descriptors to resolve in parallel the promises that do I/O.


Overview

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node by js_of_ocaml.

In Lwt,

  • The core library Lwt provides promises...
  • ...and a few pure-OCaml helpers, such as promise-friendly mutexes, condition variables, and mvars.
  • There is a big Unix binding, Lwt_unix that binds almost every Unix system call. A higher-level module Lwt_io provides nice I/O channels.
  • Lwt_process is for subprocess handling.
  • Lwt_preemptive spawns system threads.
  • The PPX syntax allows using all of the above without going crazy!
  • There are also some other helpers, such as Lwt_react for reactive programming. See the table of contents on the linked manual pages!

Installing

  1. Use your system package manager to install a development libev package. It is often called libev-dev or libev-devel.
  2. opam install conf-libev lwt

Documentation

We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:

  • The current manual can be found here.
  • Mirage has a nicely-written Lwt tutorial.
  • An example of a simple server written in Lwt.
  • Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from the excellent Real World OCaml, but are just as useful if you are not reading the book.

Note: much of the current manual refers to 'a Lwt.t as "lightweight threads" or just "threads." This will be fixed in the new manual. 'a Lwt.t is a promise, and has nothing to do with system or preemptive threads.


Contact

Open an issue, visit Discord chat, ask on discuss.ocaml.org, or on Stack Overflow.

Release announcements are made on discuss.ocaml.org. Watching the repo for "Releases only" is also an option.


Contributing

  • CONTRIBUTING.md contains tips for working on the code, such as how to check the code out, how review works, etc. There is also a high-level outline of the code base.
  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)
  • The documentation always needs proofreading and fixes.
  • You are welcome to pick up any other issue, review a PR, add your opinion, etc.
  • Any feedback is welcome, including how to make contributing easier!

Libraries to use with Lwt

Dependencies (5)

  1. ocplib-endian
  2. dune-configurator
  3. cppo build & >= "1.1.0"
  4. ocaml >= "4.08" & < "5.5"
  5. dune >= "2.7"

Dev Dependencies (3)

  1. bisect_ppx with-test
  2. odoc with-doc & >= "2.3.0"
  3. ocamlfind with-dev-setup & >= "1.7.3-1"

  1. 0install >= "2.15.1"
  2. aches-lwt
  3. activitypub
  4. albatross
  5. alcotest-lwt
  6. alcotest-mirage
  7. ambient-context-lwt
  8. amqp-client >= "1.1.0"
  9. amqp-client-lwt
  10. angstrom-lwt-unix >= "0.11.0"
  11. anthill
  12. anycache-lwt
  13. archi-lwt
  14. arp
  15. awa-mirage
  16. aws-lwt
  17. aws-s3-lwt < "4.4.0" | >= "4.8.1"
  18. awsm-lwt
  19. azure-cosmos-db
  20. balancer
  21. bastet_lwt
  22. bistro
  23. brisk-reconciler
  24. brozip
  25. builder
  26. builder-web
  27. bun >= "0.3.3"
  28. cachet-lwt
  29. calculon
  30. caldav
  31. camltc
  32. canary
  33. capnp-rpc-lwt < "2.0"
  34. capnp-rpc-unix < "2.1"
  35. caqti-mirage
  36. carton < "1.0.0"
  37. carton-git
  38. carton-lwt
  39. catala-format >= "0.2.0"
  40. cf-lwt
  41. chamelon
  42. chamelon-unix
  43. chamo
  44. charrua-client
  45. charrua-unix
  46. chess_com_api
  47. ciao_lwt
  48. clz
  49. cmdtui-lambda-term
  50. coap
  51. coap-server-lwt
  52. cohttp-curl-lwt
  53. cohttp-lwt
  54. cohttp-lwt-jsoo
  55. cohttp-lwt-unix
  56. cohttp-mirage
  57. cohttp-server-lwt-unix
  58. comby
  59. comby-semantic
  60. conan-lwt
  61. conduit-lwt
  62. conduit-lwt-unix
  63. cowabloga
  64. crunch
  65. cstruct-lwt
  66. csv-lwt
  67. ctypes >= "0.15.0" & < "0.21.1"
  68. ctypes-foreign >= "0.21.1"
  69. curl_lwt
  70. current
  71. current-albatross-deployer
  72. current_docker
  73. current_examples
  74. current_git
  75. current_github
  76. current_gitlab
  77. current_ocluster
  78. current_rpc
  79. current_slack
  80. current_web
  81. dap
  82. data-encoding < "0.1.1"
  83. devkit >= "1.2"
  84. distributed-lwt
  85. dkim-bin < "0.8.0"
  86. dkim-lwt-unix
  87. dkim-mirage
  88. dlm
  89. dmarc
  90. dns-certify
  91. dns-cli
  92. dns-client < "7.0.3"
  93. dns-client-lwt
  94. dns-client-mirage
  95. dns-forward
  96. dns-forward-lwt-unix
  97. dns-lwt
  98. dns-mirage
  99. dns-resolver
  100. dns-server
  101. dns-stub
  102. dnsrobot
  103. dnssd
  104. docker_hub
  105. docteur >= "0.0.2"
  106. docteur-solo5
  107. docteur-unix >= "0.0.5"
  108. doi2bib
  109. dream
  110. dream-httpaf
  111. dream-pure
  112. dream-serve
  113. dropbox
  114. dune >= "3.17.2"
  115. dune-rpc-lwt
  116. earlybird
  117. elasticsearch-cli
  118. emoji = "2.0.0"
  119. equinoxe
  120. ethernet
  121. ez_api >= "1.2.0"
  122. ezcurl-lwt
  123. ezjs_min < "0.2"
  124. ezjsonm-lwt
  125. ezresto
  126. ezresto-directory >= "0.5"
  127. faraday-lwt
  128. faraday-lwt-unix
  129. fat-filesystem
  130. fiber-lwt
  131. fsevents-lwt
  132. fswatch_lwt
  133. gdbprofiler
  134. git
  135. git-cohttp
  136. git-cohttp-unix
  137. git-kv >= "0.2.0"
  138. git-mirage
  139. git-paf
  140. git-unix >= "3.2.0"
  141. github
  142. github-hooks
  143. github-unix >= "4.4.0"
  144. gitlab-unix
  145. gitlab_pipeline_notifier
  146. gluten-lwt
  147. gluten-lwt-unix < "0.4.0"
  148. gluten-mirage < "0.4.0"
  149. graphql-lwt
  150. gremlin
  151. grpc-lwt
  152. guardian
  153. gufo
  154. h1
  155. h1-lwt-unix
  156. h2-lwt
  157. h2-lwt-unix < "0.10.0"
  158. h2-mirage
  159. happy-eyeballs-lwt
  160. happy-eyeballs-mirage
  161. hidapi-lwt
  162. hiredis >= "0.6"
  163. hl_yaml
  164. hockmd
  165. http-lwt-client
  166. http-mirage-client
  167. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  168. httpaf-lwt-unix
  169. httpun-lwt
  170. httpun-mirage
  171. httpun-ws-lwt
  172. hvsock
  173. i3ipc
  174. influxdb-lwt
  175. inotify >= "2.4"
  176. inquire < "0.3.0"
  177. interface-prime-lwt
  178. ip2location
  179. ip2locationio
  180. ip2whois
  181. ipv6-multicast-lwt
  182. irc-client-lwt
  183. irc-client-lwt-ssl
  184. irc-client-tls
  185. irmin
  186. irmin-bench
  187. irmin-chunk
  188. irmin-cli
  189. irmin-client
  190. irmin-containers
  191. irmin-fs
  192. irmin-git
  193. irmin-graphql
  194. irmin-http
  195. irmin-indexeddb
  196. irmin-layers
  197. irmin-mirage-git
  198. irmin-mirage-graphql
  199. irmin-pack
  200. irmin-server
  201. irmin-test
  202. irmin-unix
  203. irmin-watcher
  204. joolog
  205. jose < "0.9.0"
  206. js_of_ocaml-lwt >= "3.5.0"
  207. jsoo_broadcastchannel
  208. jsoo_storage
  209. jupyter
  210. jupyter-kernel
  211. kafka < "0.5"
  212. kafka_lwt
  213. kappa-library
  214. ke >= "0.5"
  215. kinetic-client
  216. kubecaml
  217. lambda-runtime
  218. lambda-term >= "3.3.3"
  219. lambda_streams_lwt
  220. launchd
  221. ldp
  222. learn-ocaml
  223. learn-ocaml-client
  224. ledgerwallet >= "0.4.0"
  225. letsencrypt
  226. letsencrypt-app
  227. letsencrypt-dns
  228. letters
  229. lichess_api
  230. links >= "0.9.1"
  231. llama
  232. lru_cache
  233. lwt-canceler
  234. lwt-dllist
  235. lwt-exit
  236. lwt-parallel
  237. lwt-pipe
  238. lwt-pipeline
  239. lwt-watcher
  240. lwt_camlp4
  241. lwt_direct != "6.0.0~beta01"
  242. lwt_ppx >= "6.0.0"
  243. lwt_react
  244. lwt_retry
  245. lwt_ssl
  246. mariadb >= "1.2.0"
  247. markdown_monolith
  248. markup = "0.7.6"
  249. markup-lwt
  250. mdx
  251. mechaml
  252. mehari-lwt-unix
  253. mehari-mirage
  254. memtrace-mirage
  255. metrics-influx
  256. metrics-lwt
  257. metrics-unix
  258. mimic
  259. mindstorm-lwt
  260. mirage < "4.0.0"
  261. mirage-block >= "2.0.1"
  262. mirage-block-ccm
  263. mirage-block-combinators
  264. mirage-block-lwt
  265. mirage-block-partition
  266. mirage-block-ramdisk
  267. mirage-block-solo5
  268. mirage-block-unikraft
  269. mirage-block-unix >= "2.14.2"
  270. mirage-block-xen
  271. mirage-channel >= "4.0.1"
  272. mirage-channel-lwt
  273. mirage-clock-lwt
  274. mirage-clock-unix < "4.2.0"
  275. mirage-console-lwt
  276. mirage-crypto-rng < "0.11.3"
  277. mirage-crypto-rng-lwt
  278. mirage-crypto-rng-mirage
  279. mirage-device >= "2.0.0"
  280. mirage-flow >= "3.0.0"
  281. mirage-flow-combinators
  282. mirage-flow-lwt
  283. mirage-flow-unix
  284. mirage-fs >= "4.0.0"
  285. mirage-fs-lwt
  286. mirage-kv >= "3.0.1"
  287. mirage-kv-lwt
  288. mirage-kv-unix
  289. mirage-net >= "4.0.0"
  290. mirage-net-lwt
  291. mirage-net-macosx
  292. mirage-net-solo5
  293. mirage-net-unikraft
  294. mirage-net-unix
  295. mirage-net-xen
  296. mirage-profile
  297. mirage-protocols >= "7.0.0"
  298. mirage-protocols-lwt
  299. mirage-qubes
  300. mirage-qubes-ipv4
  301. mirage-runtime
  302. mirage-sleep
  303. mirage-solo5
  304. mirage-stack = "3.0.0"
  305. mirage-stack-lwt
  306. mirage-time >= "3.0.0"
  307. mirage-time-lwt
  308. mirage-time-unix
  309. mirage-types-lwt
  310. mirage-unikraft
  311. mirage-unix
  312. mirage-vnetif
  313. mirage-xen
  314. monorobot
  315. mqtt
  316. mrmime >= "0.5.0"
  317. multipart-form-data
  318. multipart_form >= "0.2.0" & < "0.4.0"
  319. multipart_form-cohttp-lwt < "0.6.0"
  320. multipart_form-lwt
  321. naboris
  322. nbd >= "4.0.3"
  323. nbd-tool
  324. nbd-unix
  325. neo4j_bolt
  326. nottui-lwt
  327. notty-community
  328. nproc
  329. nsq
  330. obuilder
  331. obus >= "1.2.1"
  332. ocluster-api
  333. ocluster-worker
  334. ocplib-resto
  335. ocsigenserver
  336. ocsipersist
  337. ocsipersist-dbm
  338. ocsipersist-lib
  339. ocsipersist-pgsql
  340. ocsipersist-sqlite
  341. oframl
  342. ojs_base
  343. omigrate
  344. oneffs
  345. opam-check-npm-deps >= "4.1.0"
  346. opam-publish >= "3.0.0"
  347. opencage
  348. opentelemetry-client-cohttp-lwt
  349. opentelemetry-cohttp-lwt >= "0.4"
  350. opentelemetry-lwt
  351. opium
  352. opium-graphql
  353. opium_kernel
  354. opomodoro
  355. order-i3-xfce
  356. ordma
  357. oskel >= "0.3.0"
  358. ounit-lwt < "2.2.0"
  359. ounit2-lwt
  360. owork
  361. ozulip
  362. paf
  363. paf-cohttp
  364. passage < "0.1.8"
  365. pcap-format < "0.5.2"
  366. petrol
  367. pgn_parser
  368. pgx_lwt
  369. pgx_lwt_mirage
  370. pgx_lwt_unix < "2.0"
  371. piaf < "0.2.0"
  372. picos_meta
  373. plebeia >= "2.0.0"
  374. plotkicadsch
  375. posix-getopt >= "4.0.2"
  376. ppx_defer >= "0.4.0"
  377. ppx_deriving_rpc
  378. ppx_rapper_lwt
  379. proc-smaps
  380. prof_spacetime
  381. prometheus
  382. prometheus-app
  383. promise_jsoo_lwt
  384. protocol-9p
  385. protocol-9p-unix
  386. proton
  387. pxshot
  388. qcow
  389. qcow-stream
  390. qcow-tool
  391. qcow-types
  392. qdrant < "0.2.0"
  393. qfs >= "0.5"
  394. quests
  395. quickterface
  396. rawlink < "2.1"
  397. rawlink-lwt
  398. rdf_json_ld
  399. rdf_lwt
  400. redis-lwt
  401. reparse-lwt
  402. reparse-lwt-unix
  403. resource-pooling
  404. resp
  405. resp-mirage >= "0.10.0"
  406. resp-unix >= "0.10.0"
  407. resto
  408. resto-cohttp-client >= "0.4"
  409. resto-cohttp-self-serving-client
  410. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  411. resto-directory >= "0.4"
  412. riak
  413. ringo-lwt
  414. river
  415. rock
  416. rpclib-js
  417. rpclib-lwt
  418. SZXX < "4.0.0"
  419. sanddb
  420. scgi
  421. sendmail-lwt
  422. sendmail-mirage
  423. serial
  424. server-reason-react
  425. session-cohttp-lwt
  426. session-cookie-lwt
  427. session-postgresql-lwt
  428. sessions
  429. shared-block-ring
  430. shared-memory-ring-lwt
  431. sherlodoc
  432. sihl < "0.2.0"
  433. slack
  434. slacko
  435. slipshow
  436. smtml >= "0.7.0"
  437. speed
  438. spin < "0.8.0"
  439. spoke
  440. statocaml
  441. stk
  442. stog
  443. swapfs
  444. syguslib-utils
  445. syndic >= "1.4" & < "1.6.0"
  446. tar-mirage
  447. tar-unix
  448. tcpip
  449. telegraml
  450. terminus
  451. testcontainers
  452. testo-lwt
  453. tidy_email
  454. timmy-lwt
  455. tls >= "0.10.6" & < "0.16.0"
  456. tls-lwt
  457. tls-mirage
  458. tube
  459. tuntap
  460. twirp_cohttp_lwt_unix
  461. uring
  462. uspf
  463. uspf-lwt
  464. uspf-mirage
  465. utcp
  466. utop
  467. uwt
  468. vchan
  469. vchan-unix
  470. vchan-xen
  471. vercel
  472. vhd-format-lwt
  473. vmnet
  474. vue-jsoo < "0.3"
  475. wayland < "2.0"
  476. webauthn
  477. xen-evtchn
  478. xen-evtchn-unix
  479. xen-gnt
  480. xen-gnt-unix
  481. xenstore
  482. xenstore-tool
  483. xenstore_transport
  484. xlsx2csv
  485. yocaml_git
  486. yocaml_unix < "2.0.0"
  487. zarr-lwt
  488. zmq-lwt >= "5.2.1"

Conflicts

None