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

Conflicts

None