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 (27)

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. dune >= "2.7"

Dev Dependencies (3)

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

Conflicts

None